[FOLIO-817] Investigate another jekyll theme Created: 30/Aug/17 Updated: 12/Nov/18 Resolved: 22/Aug/18 |
|
| Status: | Closed |
| Project: | FOLIO |
| Components: | None |
| Affects versions: | None |
| Fix versions: | None |
| Type: | Task | Priority: | P3 |
| Reporter: | David Crossley | Assignee: | Patricia DeStefano |
| Resolution: | Done | Votes: | 0 |
| Labels: | devweb | ||
| Remaining Estimate: | Not Specified | ||
| Time Spent: | 1 week, 6 hours, 55 minutes | ||
| Original estimate: | Not Specified | ||
| Attachments: |
|
||||||||||||||||
| Issue links: |
|
||||||||||||||||
| Sprint: | |||||||||||||||||
| Description |
|
Investigation to create a custom jekyll theme that will accommodate the styled common top navigation bar for the site, a dev navigation bar, left hand navigation and content bucketing. |
| Comments |
| Comment by Patricia DeStefano [ 12/Sep/17 ] |
|
I was just about finished my 3rd branch with 3 options for everyone to look over- one branch with just the common nav bar, one branch with the common nav bar & a 2nd nav bar, and lastly, one branch with with a common nav bar, 2nd dev nav bar & left hand navigation. Then, Peter Murray & I met with the EBSCO marketing web team and other partners. The EBSCO marketing web team also looked over dev.folio.org. They had some recommendations as well. Once I hear back from them to verify how to accommodate the team's recommendations, I can post the top navigation recommendation (it has changed...) in
|
| Comment by Patricia DeStefano [ 13/Oct/17 ] |
|
I have created a POC for dev.folio.org that incorporates the following FOLIO partner revision recommendations:
The following recommendations can be added, but are not in the POC now:
In the POC examples... If a developer is interested in the Guidelines for Contributing Code -> Labels, Sections, Nav bars, etc can all be adjusted, deleted and moved around. Assuming that you have jekyll installed, you can follow the instructions below to clone my fork and check it out:
|
| Comment by David Crossley [ 17/Oct/17 ] |
|
I have commenced investigation. There are many changes. It will take some time to assess. |
| Comment by David Crossley [ 24/Oct/17 ] |
|
I will gradually add some comments. However not expecting you to modify the PoC. |
| Comment by David Crossley [ 24/Oct/17 ] |
|
The Curriculum is in a separate repository. When it deploys, it is published to dev.folio.org/curriculum/ I gather that this is deliberate, so that it is completely stand-alone and concise. |
| Comment by David Crossley [ 24/Oct/17 ] |
|
The developers have decided to have the main documentation of each module alongside its code. For example the Okapi Guide is at Okapi, the docs for each of the Stripes Components Other high-level documentation is to be here at dev.folio.org, with links to that documentation. Yes some of it may be better moved to dev.folio.org, but most will remain together with its code. |
| Comment by David Crossley [ 01/Nov/17 ] |
|
Regarding the display of logos of key organisations, see a proposal at
Your PoC has few examples on the bottom of the front page. The proposal would accomodate more. |
| Comment by David Crossley [ 01/Nov/17 ] |
|
Splitting the documentation into small pieces frightens me. It is not how i read stuff, and not how the developers wrote the Okapi Guide and Stripes Developers docs for example. Perhaps some docs are relevant to keep whole, with links to main sections in the left-side panel. Rearrangement will cause many broken links in this documentation and in the docs at each github repository. I suppose that we can cope with that, but there will be problems for a while. |
| Comment by David Crossley [ 01/Nov/17 ] |
|
I feel that this theme is complex and might be difficult to maintain. Is it based on a version of some available product? |
| Comment by David Crossley [ 01/Nov/17 ] |
|
The site needs to be available to Asian developers, so it currently uses a CDN that is reliable there to get the jQuery JS. So do we really need to use Google fonts? That might not be readily available. |
| Comment by Peter Murray [ 01/Nov/17 ] |
|
Patricia DeStefano - David pointed me to this ticket a little while ago. The new design is coming along fine. I can't recall exactly why I create a separate repository for the curriculum. I think I had in mind that people who were only tangentially related to the project could submit corrections and pull requests against the curriculum only without having access to the wider dev.folio.org site. If merges to master are protected here on GitHub, that becomes less of a concern, I suppose. |
| Comment by Patricia DeStefano [ 01/Nov/17 ] |
|
Let me see if I can address some of your comments with regards to the POC. The directories in the POC project correspond to the sections on the dev navigation bar. So, if you are looking to edit a webpage in the guidelines section, the corresponding markdown will be in the _guidelines directory. So, to make some common updates... To Edit an Existing Page: To Add a New Page to an Existing Section: Thanks for the access information about the Curriculum repo Peter Murray. I placed the Curriculum in the Tutorials section for the POC, but it can be placed anywhere you would like. My thinking was to align it with the rest of the site. It did lend itself to be dropped very easily in since you already had the left hand nav. Also, you can place a number of tutorials in that section in the future….all unified, in the same place, with the same look and feel. It can still be placed in a separate repo if you desire, but we may want to apply the theme to the additional repo too so that the user can navigate back. Either way, we could link out for now to the separate repo if it is an issue and think about it later. Breaking up the documentation into logical smaller sections avoids a wall of text, which can increase bounce rates. Just to be clear…this is just for the document site docs…we are not touching anything in the github source repos in the POC. "Rearrangement will cause many broken links in this documentation and in the docs at each github repository." Can you give me an example from the POC so that I can address it? I thought that I checked all of the links, but could have missed something. I also tried to make sure that all of the information that was in dev.folio.org at the time of my last sync is in the new POC….just divided into the different sections. Any of the sections or content in the sections can be changed if you prefer it a different way…just let me know...it can easily be adjusted. Replaced the jQuery JS with the CDN source….will push that up. Google Fonts are one of the top sources for typefaces. That said, if something was to happen, we have several web font fallbacks in line. We can table bringing the information from the individual github repos into the site if you would like. That is not included in this POC…so, that can be discussed at a later time to see if it is worthwhile. The links out to the different repos are all still there in the POC. After we satisfy the first set of recommendations from the partners, we can see where to go next. Please let me know if I can help in any way of if you need any further information. |
| Comment by Peter Murray [ 03/Nov/17 ] |
|
Thanks for your work on the Proof-of-Concept Patti. Some comments: Left sidebar navigationWhen there is only one page in a section on the left sidebar, one has to click twice to get to it. For instance, starting at http://127.0.0.1:4000/getstarted/index/, one needs to click on "Front End" then "Primer for Front-End Development" to get to the next page. When there is only one sub-page under a left nav heading, this extra click shouldn't be necessary. The styling of the links in the left navbar is weird. If I haven't visited a page on the left navbar, the link text is black. If I have visited a page, the link text is blue. I'd prefer black for both. URL structureThe root pages of sections on the top nav bar are inside an "index" directory. A typical navigation pattern wouldn't include this. e.g., rather than http://127.0.0.1:4000/getstarted/index/ the URL should be http://127.0.0.1:4000/getstarted/ The URLs for the curriculum pages are going to change. I'm not so sure that is a problem as long as they are internally consistent. On further reflection, I don't think it is going to be an issue to put the curriculum content into the main folio-org repo and deprecate the existing curriculum repo. Project-wide navigationHas this been nailed down yet? What is in the Proof-of-Concept is missing some top-level headings, no? OtherThe "Improve this page" link on the bottom of each page doesn't seem to go anywhere right now. Will this point to something when it is live on the GitHub Pages site? |
| Comment by Peter Murray [ 03/Nov/17 ] |
|
Oh, missed one thing. I think using Google Fonts is okay. It is widely used and degrades nicely if not available. |
| Comment by Patricia DeStefano [ 03/Nov/17 ] |
|
Thank you for the comments Peter Murray. Will take a look on Monday, but looking at it now...doesn't look like your requests will be a problem to implement in the theme. The "Improve this Page" was to be able to directly edit the pages in Github (not linked yet). Guessing we don't want to be able to do that at the moment. So, I can disable that for now. The top nav was the latest that I had from the FOLIO Marketing Meeting we attended on August 30th at EBSCO, but I can circle back and check that again. |
| Comment by David Crossley [ 06/Nov/17 ] |
|
Regarding my past comments about potential difficulty of maintenance. With the current theme we know exactly where the theme files come from and which version, i.e. presently classic-jekyll-theme v1.9.3 for our _layouts and _sass directories and other theme files. Any subsequent changes that we may need to make are then clearly documented in our revision control system. Any theme tweaks are isolated into our own SCSS files, etc. Also, when next the upstream theme files are modified, we can follow and update our copies accordingly to synchronise with the new version. |
| Comment by David Crossley [ 06/Nov/17 ] |
|
In the classic-jekyll-theme, all of the CSS is a separate concern, so it is easy to modify. However this theme has CSS (e.g. for colors and font-sizes) mixed in with the layout and other things. Compare each: cd _includes; grep "style=" *.html |
| Comment by Peter Murray [ 06/Nov/17 ] |
Oh! Okay. I didn't see that as I was running Jekyll locally.
Thanks for checking in with the web development team. The latest version of the wireframes shown at the product council meeting last month had one additional pull-down list – "Overview" – to the left of "Developers". I think this is getting close to final, but I'm at a loss to say how close. |
| Comment by Patricia DeStefano [ 06/Nov/17 ] |
|
Verifying the latest top nav from the FOLIO partners. I will address the requests for the theme as well. |
| Comment by David Crossley [ 14/Nov/17 ] |
|
I have done investigation to find the basis for this theme. It seems to be from https://github.com/aksakalli/jekyll-doc-theme |
| Comment by Patricia DeStefano [ 14/Nov/17 ] |
|
Yes, that is the theme that I showed to you guys in Ireland. I thought it was closer to what the FOLIO partners might be looking for then, but does not satisfy our needs. So, I used the pieces that I liked/could from that theme & the POC ended up being a combination of many things - theme pieces, organization via additional jekyll, and additional styling....whatever was needed to form an organized theme that suits the needs of the FOLIO partners. Since using an existing theme out of the box will not work to align with the rest of the FOLIO suite of sites, we have to have a theme that will create the custom dev site that the FOLIO partners are looking for and organize the dev docs so that it is easy for a new developer to consume the docs. If you have any pieces of other jekyll themes (left nav, top nav, etc) that you prefer that will align...just let me know and I can drop them into the POC to check it out. I am looking at options other than accordion for left nav for the POC....just so we have it available if desired. This week, I am finishing the adjustments to the POC for Peter's requests above. I will comment back when I am finished & you can take a look and see what you think. |
| Comment by Peter Murray [ 14/Nov/17 ] |
|
Thanks for the pointer David Crossley – interesting read. Patricia DeStefano: I think I read somewhere that GitHub Pages doesn't support custom Jekyll themes. Is this going to push us towards generating the static HTML and serving it up somewhere other than GitHub pages? If so, I'm okay with that – we need to get dev.folio.org onto a place with HTTPS support, and that isn't possible with a custom domain and GitHub pages. Since we have other resources on AWS, I'd be inclined to do something like Using AWS CodePipeline and CodeBuild to update a Jekyll website. That mimics how GitHub Pages works, but gives us enough flexibility to customize and do HTTPS. |
| Comment by Patricia DeStefano [ 14/Nov/17 ] |
|
Hi Peter Murray... You are correct. GitHub pages only supports some gem based themes, but this is just a regular theme in our Jekyll directory. More info here - https://jekyllrb.com/docs/themes/ I can strip the folio specific docs out of the POC and publish just the un-built theme to my github pages to check it out that way. I think that we are fine with deploying it to Github pages if desired, but your option to deploy it should definitely be looked at. |
| Comment by David Crossley [ 15/Nov/17 ] |
|
Peter Murray any theme can be used. GitHub Pages has a set of basic themes that can be used automatically (e.g. when we started we were using "minima"). The theme that we are currently using is not from that set, but is "classic-jekyll-theme" (
Yes there are other reasons that we might consider using a different infrastructure for building and deploying (see
|
| Comment by David Crossley [ 15/Nov/17 ] |
|
Patricia DeStefano thanks for the explanation of the theme. I do recall your brief chance to demonstrate in Dublin. I have been asking since where it came from, as i am very concerned about ongoing maintenance and development, especially of a piecemeal theme. We are a small group and need to focus on content. |
| Comment by Patricia DeStefano [ 15/Nov/17 ] |
|
No problem David Crossley, but please base your investigations on what you see in the actual POC theme because it follows the layout/design that the FOLIO partners decided on. I organized the POC theme keeping in mind both theme usage and the end result website design. Please let me know if I can provide any further usage descriptions. Yes, I agree, content is always the focus, but the larger group wants it organized differently and needs to see the navigation align with the rest of the sites. |
| Comment by Patricia DeStefano [ 16/Nov/17 ] |
|
I circled back to the web team and they sent me the latest top navigation wireframe from your product council meeting Peter Murray. I have attached it here with the new drop down open. I should have all your requests and the new top nav incorporated into the POC today. |
| Comment by Peter Murray [ 16/Nov/17 ] |
|
Perfect! Thanks, Patricia DeStefano! |
| Comment by Peter Murray [ 16/Nov/17 ] |
|
I'm probably jumping the gun here Patricia DeStefano, but I love the latest changes to your dev.folio.org branch. The URLs are cleaner, and the left sidebar function is more intuitive. |
| Comment by Patricia DeStefano [ 16/Nov/17 ] |
|
Finished the requests from Peter Murray and have pushed the changes to my fork. Assuming that you have jekyll installed, you can follow the instructions below to clone my fork and check it out: Included in the changes: 1 - When there is only one item in a section, I eliminated the accordion resulting in less clicks. You can choose now in the yml if you would like an accordion heading or not. 2 - Changed everything to black visited, etc. in the left hand nav. 3 - Removed the reference to index in the subdirectories. I agree, that was confusing. 4 - Adjusted the top navigation to align with the FOLIO requirements - images changed a bit, added a drop down and right aligned the dev nav bar. 5 - Removed the "Improve this page" link from the bottom of each page. Please let me know if you have any questions or anything else that you would like changed. |
| Comment by Patricia DeStefano [ 16/Nov/17 ] |
|
Thanks Peter Murray! Could you check the Overview links? I know they will probably change as the other sites develop, but for now...let me know if you guys would like anything different there. Also, the accordions in the left hand nav are beneficial for mobile devices because they save space, but to save clicks we could look at non accordion left hand nav to compare. I could place one left hand nav in a section as non accordion to see what all of you would like it better...could simplify it a bit if that is a concern. Just let me know if you have any other changes that you would like me to include. |
| Comment by David Crossley [ 22/Nov/17 ] |
|
The left-hand menus do seem to be an improvement on your previous PoC. |
| Comment by David Crossley [ 22/Nov/17 ] |
|
There is something that i find confusing with the documents now being individual pieces and having strange URLs. For example consider the "Release procedures" document. With the current site, we go to the whole document at "/doc/release-procedures" and go to a specific section, e.g. "/doc/release-procedures#gradle-based-modules". With this PoC, we go to the initial part at "/devguides/release-procedures/" and to that other part at "/devguides/gradle/" (so it has lost the context of "release-procedures"). I would expect "/devguides/release-procedures/gradle/" etc. |
| Comment by David Crossley [ 22/Nov/17 ] |
|
With the current site, we have a useful "html/head/title" for each page (it uses Liquid in _includes/head.html to compose that). For example "FOLIO Developer | Release procedures". This has various benefits:
However with this PoC, there are multiple ones that just have "FOLIO Developer | Introduction". Not sure how to fix that. |
| Comment by David Crossley [ 22/Nov/17 ] |
|
With a usual browser window width of 1024px (e.g. GitHub size) then the top navbars do fit okay. We still need to add a "Search" menu. So maybe need one less, or perhaps change text of "Getting Started" to just "Start", to make some room. Shrinking the browser window width just a little, then the top navbars expand to three lines. (The classic-jekyll-theme handles this better.) There is still horizontal space available, so i wonder if it can be better utilised. |
| Comment by David Crossley [ 22/Nov/17 ] |
|
I am not expert at git-branch-and-merge. I wonder how we can get your branch (or branches) into the main repository so that they can be built with Peter's upcoming AWS build infrastructure (
|
| Comment by Peter Murray [ 22/Nov/17 ] |
|
> I am not expert at git-branch-and-merge. I wonder how we can get your branch (or branches) into the main repository so that they can be built with Peter's upcoming AWS build infrastructure (
The way I'm structuring it, the only thing that would be required is to create a branch on the folio-org/folio-org.github.io repository. Patti: I think you have permissions to push a branch to that repo; if not, let me know and I can make that happen. |
| Comment by Patricia DeStefano [ 22/Nov/17 ] |
|
I am off most of today until Monday for the holiday, but just wanted to leave a quick comment. I can look at all David's comments from today on the POC and accommodate and/or comment next week. To get my branch into the main project repo - In your local directory for the main project - I think that you guys can set a remote to my forked repo. Then, pull my branch into your local directory for the main project repo. Then, push my branch up to the main project repo. Happy Thanksgiving! |
| Comment by Peter Murray [ 27/Nov/17 ] |
|
The AWS-based system isn't quite ready yet. I made it mostly to the end, but now I realize I have to back-track a little bit in order to get the GitHub Status API calls done efficiently/correctly. (It means I'm going to have to break up my existing all-in-one AWS Lambda into at least two parts.) Hoping to have this ready this week. Then we can bring Patricia DeStefano's branch onto AWS. |
| Comment by Patricia DeStefano [ 01/Dec/17 ] |
|
It was mentioned that it would be desirable to have the secondary top navigation bar also collapse for mobile. I put that functionality into the POC branch today and will push it up to my fork branch on Monday. |
| Comment by Peter Murray [ 04/Dec/17 ] |
|
Sounds good – thanks, Patti. |
| Comment by Patricia DeStefano [ 04/Dec/17 ] |
|
Collapsing secondary top navigation is now in the POC branch. Assuming that you have jekyll installed, you can follow the instructions below to clone my fork and check it out: |
| Comment by Peter Murray [ 04/Dec/17 ] |
|
Thanks, Patti. Once I get
|
| Comment by Peter Murray [ 08/Dec/17 ] |
|
Patricia DeStefano: I got your branch up on the main site. I had to add `buildspec.yml` (for the AWS CodeBuild processor) and update `Gemfile.lock` in order to get it to build in AWS. Those files are in the branch I pushed up to GitHub: https://github.com/folio-org/folio-org.github.io/tree/folio-817-top-side-nav |
| Comment by Patricia DeStefano [ 08/Dec/17 ] |
|
Thanks Peter Murray! I think that the best link to get an idea is http://folio-817-top-side-nav.dev.folio.org.s3-website-us-east-1.amazonaws.com/tutorials/foliocurriculumintro/ because the shorter sections need more content. I mentioned that if you would like to use the left hand navigation to go up and down one page instead of page to page, we can try that...seems like it might be a good compromise. It would require some more work on my POC, but if you would like to try it...let me know and I will check here. |
| Comment by Peter Murray [ 11/Dec/17 ] |
|
Please take a look at that, Patti. The overwhelming number of comments seem to favor longer pages with a table-of-contents widget over more shorter pages. |
| Comment by Patricia DeStefano [ 11/Dec/17 ] |
|
Sure Peter. Just commented in Slack as well...I did not have navigation up and down the page, but figured every visible section in the POC would be full of content...sorry if that was not clear in the POC...I was basically creating the theme & only divided the content...did not add any. I think that looking at the tiny pages might have threw people off...those were intended to be full of content. I think that I can accommodate everyone. My proposal at this point...So, the secondary navigation bar serves as the toc headers...so, I will leave that for now. In each toc section (Getting Started, Guides, etc), I will make the shorter pages into longer and change the sidebar to be fixed and navigate up and down the longer section. I can play with putting the toc headers from the secondary nav bar into the sidebar as well if we desire, but if we already have them in the secondary nav bar it might be a bit redundant. I also just put the search back in for the entire project...I put it back in as search box directly in the secondary nav bar. So, the secondary nav serves another purpose as well. I have not pushed that to my branch yet, but will. |
| Comment by David Crossley [ 12/Dec/17 ] |
|
I do not think that it was the tiny content of some pages being misleading for people. They much prefer using one page per topic. Please be careful adding extra actual content to this PoC at this stage. |
| Comment by David Crossley [ 18/Dec/17 ] |
|
The demonstration is at folio-817-top-side-nav (Not meaning to rush you with any pending improvements, just updating all related issues.) |
| Comment by Patricia DeStefano [ 06/Jan/18 ] |
|
Have been making updates for the left hand menu to the forked version: clone the project - git clone https://github.com/pdestefano/folio-org.github.io.git |
| Comment by David Crossley [ 09/Jan/18 ] |
|
There are many changes in one commit, so it is difficult to keep up. I provide some comments below. I do appreciate your efforts. |
| Comment by David Crossley [ 09/Jan/18 ] |
|
I had been trying to use a minimum of JavaScript. Now there is lots. (But okay if that is what is needed.) I am concerned that this is using a very old version of "jquery-ui". Also the "tocify" seems to be a non-responsive and old repository. I had considered it a while ago, but stopped. Following some of its open issues led to the stand-alone "tocbot" instead (see some investigation in our FOLIO-978). |
| Comment by Patricia DeStefano [ 09/Jan/18 ] |
|
Sure, I can address your concerns and look at versions, options for toc generation etc. I am just in the midst of getting this version completely styled, adding the new requested functionality and latest content. As soon as I am finished with that, I will move onto your concerns as well. |
| Comment by David Crossley [ 24/Jan/18 ] |
|
Today i updated the master to incorporate the changes from
_config.yml (minor)
_includes/head.html (minor)
_includes/footer.html (minor)
_layouts/page.html (new)
_sass/_folio.scss
No changes to Gemfile. The directory _sass/classic/ is not needed since early December, as we use "jekyll-remote-theme" plugin. Updates to actual content are minor, mostly related to frontmatter for that theme's menus. |
| Comment by Patricia DeStefano [ 24/Jan/18 ] |
|
Thanks for the update. I should have two POC branches pushed up to my fork tomorrow with my updates. |
| Comment by David Crossley [ 25/Jan/18 ] |
|
Beaut, thanks. I will be away for the next few days, so will investigate next week. |
| Comment by Patricia DeStefano [ 25/Jan/18 ] |
|
I have pushed up a new POC branch to my fork. Assuming that you have jekyll installed, you can follow the instructions below to clone my fork and check it out: clone the project - git clone https://github.com/pdestefano/folio-org.github.io.git POC folio-817-hor-vert-navb Branch Summary:
A little about the custom theme/framework...
I can make my other POC branch using tocify look and function the same as this branch using tocbot if desired. Since it seems that tocbot is preferred, I decided not to take the time to update the tocify branch unless it is desired. Please let me know if you have any questions. |
| Comment by David Crossley [ 30/Jan/18 ] |
|
Thanks. This is much improved. The navigation presentation is more compact, now fitting the ideal browser window width. I do have some general concerns about CSS style, but will leave those until later (e.g. in-line code elements are too emphatic; lost API table formatting; why coloured headings). Not expecting all of the following items to be fixed in this proof-of-concept. But we do need to be sure that they can be handled. |
| Comment by David Crossley [ 30/Jan/18 ] |
|
The once-separate documents are being merged into single large documents (e.g. into /reference/refinfo/ and /guidelines/communityguidelines/ etc.). I reckon that that will not be as useable, regarding: browsing, referencing, maintenance, and searching. For example, the separate pages FOLIO Glossary and API documentation are being merged into "_reference/refinfo.md" Is there a reason for such amalgamation, or perhaps it is just to demonstrate theme ability? |
| Comment by David Crossley [ 30/Jan/18 ] |
|
Tutorials: Need the infrastructure for multiple tutorials, and each potentially having multiple pages (see
|
| Comment by David Crossley [ 30/Jan/18 ] |
|
Each directory is missing its landing page, e.g. /reference/ and /tutorials/ etc. Each needs an index.html |
| Comment by David Crossley [ 30/Jan/18 ] |
|
We have some documents that are not linked into the navigation menus, yet should appear to belong to a certain area of the site. For example, http://dev.folio.org/doc/code-analysis/ has the "Documentation" area highlighted at the top and left-hand navigation menus. (That is actually not a good example, as it will get linked to the menus when the re-arrangement happens. But this does show the feature.) As we get even more documents, they will not all be able to be linked as part of the menus, but need this indication of which section they belong to. Is this theme able to handle such? |
| Comment by David Crossley [ 30/Jan/18 ] |
|
Search: Inserting the results panel onto the current page seems strange. Search box is fiddly. Why not just use a separate page, as with the current site? This enables results to be clearly listed. It also enables search instructions to be provided. Lost the other search page which provides various GitHub searches. Also later we expect to have various different searches, e.g. using GraphQL. So need the infrastructure to enable separate additional search pages. |
| Comment by David Crossley [ 30/Jan/18 ] |
|
Lost the ability to run the bin/htmlproofer.sh facility. Locally restored it in Gemfile. It does report new issues. |
| Comment by David Crossley [ 30/Jan/18 ] |
|
I do have concerns about maintenance. With the current classic-jekyll-theme we have a minimum of extra stuff to maintain. With this theme we have much more. There is lots of use of "style" attributes in html markup, rather than separation of CSS. There is code duplication in "_layouts" and "_includes". Is there a need to have a copy of Bootstrap in the _sass directory? |
| Comment by Peter Murray [ 30/Jan/18 ] |
|
I pushed this up to the main GitHub repo as a branch, which caused a version of it to build on AWS: http://folio-817-hor-vert-navb.dev.folio.org.s3-website-us-east-1.amazonaws.com/. Note that a change to Gemfile.lock was required. |
| Comment by Patricia DeStefano [ 30/Jan/18 ] |
|
Thanks for taking a look... I can address all of your concerns...here are a few...will try to get to more tomorrow. I was under a time constraint...so I don't think inline CSS should be of concern in the short term. The CSS can be more streamlined and pulled external if you decide to use this. _layouts and _includes directories are the way they are meant to be. Each category has its own layout so that if down the road you would like a different layout for each category, you have that flexibility. The _includes directory contains portions of each layout... header, footer and navigation. Since there are other link checkers out there, I removed html-proofer because it caused an error in my environment when building. I work on a windows machine and libcurl is not by default installed. html-proofer depends on typhoneous which depends on libcurl. So, anyone trying to build the project on windows and has not already installed libcurl will hit an error. Any dependency that goes back to libcurl will cause a windows developer to hit an error if they have not previously installed libcurl - jekyll-remote-theme also depends on libcurl being installed on your machine. Just wanted to mention why I removed it...thought it would be simpler for a windows developer because there are other options...but easy to add back if desired. Will try to answer more for you tomorrow...thanks! |
| Comment by Patricia DeStefano [ 30/Jan/18 ] |
|
Thank you Peter Murray! |
| Comment by David Crossley [ 31/Jan/18 ] |
|
FOLIO developers would generally need 'curl' anyway. So will add a note to this README. |
| Comment by Patricia DeStefano [ 02/Feb/18 ] |
|
Just wanted to address the rest of your concerns. Color and table formatting can be changed to whatever preferred. Bootstrap is used for styling. I put the Glossary and API docs together in one page because they are both reference, demonstrate capability and you guys were desiring longer pages. They can easily be separated into separate pages like the guide section. For the tutorial section, I adjusted it so that you can have each tutorial title as the 1st level heading and each tutorial can have multiple pages (lessons) underneath (might be overkill for the other sections). I have attached an image that makes that easier to see (
|
| Comment by David Crossley [ 03/Feb/18 ] |
|
I realise that Bootstrap is used for styling. As part of my drive to ease maintenance, i was wondering if we need to carry a copy of its stuff (unless needing to deeply over-ride something). Could it be obtained via CDN. |
| Comment by David Crossley [ 03/Feb/18 ] |
|
Regarding separate Tutorials each with potentially separate pages: We urgently need to move the old multi-page Curriculum (
|
| Comment by David Crossley [ 03/Feb/18 ] |
No, we were not actually "desiring longer pages". The reason for the poll at
So for example, the "Reference" section should remain as separate pages. I raised this a number of times because i wondered if there was a misunderstanding. |
| Comment by Patricia DeStefano [ 14/Feb/18 ] |
|
Hello - I am going on vacation and will return to the office Feb 26th. I probably will not be able to respond to JIRA comments until then. This afternoon, I updated the content, incorporated faqs and separated the reference back into two pages - API Specifications and Glossary. I put the FAQs under the Get Started section for now. I have pushed the changes up to my POC branch below. Assuming that you have jekyll installed, you can follow the instructions below to clone my fork and check it out: clone the project - git clone https://github.com/pdestefano/folio-org.github.io.git |
| Comment by Patricia DeStefano [ 03/Apr/18 ] |
|
Hello - I received an updated top nav from the UX team here at EBSCO. It is mainly added images, color and font. Not sure if Peter Murray has received the details as well, but wanted to update the top nav template on this issue to the latest. So, attached is the latest top nav that they would like carried through all of the FOLIO sites for consistency and alignment. The responsive behavior of the top nav is slightly different than I had anticipated. I have aligned the POC branch to function according to the attached wireframes. You can try it out by following the instructions below. I have also included some screen shots of the POC included with the top nav ux wireframes. While I was in there, I also synced the POC branch with the latest content in the folio master branch (events page, video, raml-cop guide in the guide section, latest tocbot, etc.). clone the project - git clone https://github.com/pdestefano/folio-org.github.io.git |
| Comment by Peter Murray [ 04/Apr/18 ] |
|
Hi! I've seen the mockups, but I haven't seen the implementation-in-code yet. I think I found it in your branch: https://github.com/pdestefano/folio-org.github.io/blob/folio-817-hor-vert-navb/_includes/topnav.html I'm hoping for something that is a standalone fragment of HTML5 that I can plug into the various web properties...use in-line CSS styles and base64-encode images and the like. That way it can get added/updated as a unit without having to worry about external dependencies. That might be unrealistic, but it seems like a good goal to strive towards. Is there JavaScript required for the nav bar on your branch? I can't quite determine that from the browser inspector. |
| Comment by Patricia DeStefano [ 05/Apr/18 ] |
|
Hi Peter Murray! I understand what you are looking for. I used a bootstrap navbar - it provides alignment for different pieces of the nav bar, styling and responsive behavior. So, you need to include the bootstrap required js and css. Yes, topnav.html. It is separate from the markdown content. So, it could be replaced with a different nav bar without affecting the structure or content, but it would take some work to get a new nav bar to match the style and responsive behavior of the bootstrap nav bar. You could also try to use the bootstrap bar without the javascript…would require some work and more css. I think that the EBSCO marketing group is starting to implement the same thing for the top of the general site now. I am not sure how they are going to generate the site (wordpress or the like…or custom?). They are aiming for the same bar as well, but they are not using a static site generator as far as I know…so, guessing they will do it differently. Maybe what they come up with could be an option for you? |
| Comment by Peter Murray [ 05/Apr/18 ] |
|
The FOLIO marketing team is meeting right now, and I wanted to show what the navbar plan looks like at the moment, so I pushed your branch to the `folio-org` organization, which generated this: http://folio-817-hor-vert-navb.dev.folio.org.s3-website-us-east-1.amazonaws.com/ |
| Comment by Patricia DeStefano [ 05/Apr/18 ] |
|
Sounds good. Thanks...let me know if I can be of help. |
| Comment by Khalilah Gambrell [ 21/Aug/18 ] |
|
Peter Murray and Patricia DeStefano, should this user story remain open? |
| Comment by David Crossley [ 22/Aug/18 ] |
|
Ah sorry Khalilah Gambrell there are a number of old related issues that i still need to tidy and close. Yes this investigation is finished. The current theme is satisfactory
|