WIP: Global nav (MVC)
This is a test for now. This MR https://gitlab.com/gitlab-org/gitlab-ce/merge_requests/22668 is being used to change the docs' frontmatters.
UPDATE: I'll close this MR in favor of a cleaner one: !362 (merged). The current branch seems to be broken, so I'd rather start fresh.
MVC for #169 (closed)
Preview
CURRENT STATE:
- See !362 (merged)
- The nav organized by product categories (DevOps stages) ended up not looking good (see this comment). It was way too messy and busy, and some of the features belong to more than one category, so it wasn't working at all. So I went ahead and reorganized by user/admin/contributor. It doesn't hurt, from my perspective, as the CE and EE landing pages are organized by the product categories.
Previous states:
Review app: http://review-docs-docs-vx3wcw.178.62.207.141.xip.io/ce/ not working
First iteration (MVC)
-
Create the nav - Option 1: via loop + frontmatter entries
Option 2: via data YAML file created and updated manually (ingitlab-docs/content/_data
). We should avoid this approach as for each change on CE/EE that affects the nav, we'd need another MR to gitlab-docs to update the nav
-
Reposition everything properly (the 3 colums of the page: global nav | content | ToC) -
Fix buggy styles (the ToC is styled and positioned via JS, we need to fix that as it's causing other problems, e.g., https://gitlab.com/gitlab-com/gitlab-docs/issues/253 and https://gitlab.com/gitlab-com/gitlab-docs/issues/280#note_115225871) -
Remove the ToC from the main content container so that they work independently
-
-
Add active
class to highlight the page the user is at (class="global-nav-link <% if @item == doc %>active<% end %>"
) -
Add buttons to allow the user to toggle both sidebars (that works well on mobile too) -
Add expandable buttons for each category:
Current implementation
This MR uses the Nanoc Blogging helper to loop through all docs, select the ones with
UPDATE: I managed to loop through all the files with kind: article
in the frontmatter, and output them according to their categories (Plan, Create, Verify, ..., User, Admin, Development), also defined in their frontmatter.<% @items.find_all.each do |doc| %>
, which builds faster than using the blogging method.
This MR uses <% @items.find_all.each %>
to loop through all files, select the ones with a category: x
in the doc frontmatter, and output them according to their categories (Plan, Create, Verify, ..., User, Admin, Development), also defined in their frontmatter.
Notes:
-
the loop=> SOLVED!<% @items.find_all.each do |doc| %>
seems to print all files unless we restrict it to<% if doc[:category] %>
-
to make this work without repeating the span tags, I had to run the same loop for each category, which is a not-good workaround=> SOLVED! -
to make this work properly, we ideally would have to write a helper to loop through the pages and identify each category, then call them in the layout file accordingly. Smt like=> SOLVED!case doc[:category] when 'user' do 'doc_user'
then call it withdoc_user[:path]
, etc. -
the build in GitLab is timing out, but it builds locally. Takes forever, but builds.=> SOLVED with copy of default layout
Problems to solve
-
The ToC is broken bc of the lack of space in the current layout. I fixed it (for regular screens) but it's not good enough. Need FE to get rid of all that JS for the toc, and position it with proper CSS => https://gitlab.com/gitlab-com/gitlab-docs/issues/251 -
The toc JS is also causing https://gitlab.com/gitlab-com/gitlab-docs/issues/253 -
[x] Need an eng to write a helper to use the loop just once, as they're repeated over and over again to avoid outputting a category for each link: plan=> SOLVED!<link>
plan<link>
plan<link>
create<link>
create<link>
etc -
[x] We need a way to separate the docs in "DevOps stages", "User docs", "Admin docs", and "Contributor docs"=> SOLVED! -
[x] We need a way to be able to customize the order in which the links appear on the page=> SOLVED!
How to test this locally
Considering you have all set to preview the docs site locally:
-
- Open a terminal in CE:
git pull
git checkout docs-test-global-nav
-
- Open a terminal in gitlab-docs:
git pull
git checkout test-global-nav-mvc
-
bundle install
(to update the gems) bundle exec nanoc compile
bundle exec nanoc live
-
- Preview at
http://localhost:3000/ce/README.html
- Preview at
Related
- Pretty cool stuff about Nanoc here: http://clarkdave.net/2012/02/building-a-static-blog-with-nanoc/ + http://clarkdave.net/2012/05/building-a-static-portfolio-with-nanoc/