Skip to content

WIP: Global nav (MVC)

Marcia Ramos requested to merge test-global-nav-mvc into master

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)

Screenshot_2018-11-08_at_15.12.40

Current implementation

This MR uses the Nanoc Blogging helper to loop through all docs, select the ones with kind: article in the frontmatter, and output them according to their categories (Plan, Create, Verify, ..., User, Admin, Development), also defined in their frontmatter. UPDATE: I managed to loop through all the files with <% @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 <% @items.find_all.each do |doc| %> seems to print all files unless we restrict it to <% if doc[:category] %> => SOLVED!
  • 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 case doc[:category] when 'user' do 'doc_user' then call it with doc_user[:path], etc. => SOLVED!
  • 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 <link> plan <link> plan <link> create <link> create <link> etc => SOLVED!
  • [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:

    1. Open a terminal in CE:
    • git pull
    • git checkout docs-test-global-nav
    1. 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
    1. Preview at http://localhost:3000/ce/README.html

Related

Edited by Marcia Ramos

Merge request reports