Skip to content

Add script to copy and modify navigation.yaml

Sarah German requested to merge 8-global-nav-yaml into main

What does this MR do and why?

Adds scripts to migrate navigation.yaml, which is the data source of the left sidebar navigation on the website.

This is a bit different from our existing content migrations because this file is part of the gitlab-docs repository, not the source content projects (gitlab, gitlab-runner, etc).

In this case, we need to download the file on its own and omit it from Git (for now. when it's time to launch we will commit the latest version of it to this repo).

Anyways, this code should:

  1. Download navigation.yaml from the current site
  2. Replace the code comment at the top of navigation.yaml with content from a .txt file. Directions for updating the file have changed a bit.
  3. Modify the YAML structure. Using the same key names at each level of the nav object will make it much, much easier to work with the menu programmatically.
  4. Modify URLs in the YAML file:
    • Drops the /ee prefix on links. This is not used on the Hugo site.
    • Drops the .html suffix on links. Hugo renders URLs without this, unless you enable a setting called uglyUrls, which hopefully we can avoid.

Related issue: #8 (closed)

How to set up and validate locally

Numbered steps to set up and validate the change are strongly suggested.

  1. Configure a local GitLab Docs environment: https://gitlab.com/gitlab-org/technical-writing-group/gitlab-docs-hugo/-/blob/main/doc/setup.md.
  2. Run go run cmd/gldocs/main.go fetch
  3. Verify data/navigation.yaml is created and has the new comment and YAML structure (see below for an example).
  4. Check that it's valid YAML by running make lint-yaml

Don't worry that the first link (to "Home") will have an empty URL, we're removing that in gitlab-org/gitlab-docs!4756 (merged). 😄

Expected YAML (sample)
# Global navigation file for GitLab Docs
#
# For each entry:
#
# - Do not start the URL with "/".
# - URLs must be relative to root. For example, a page at https://docs.gitlab.com/runner/install/osx
#   has the entry `runner/install/osx`.
# - If you're referring to a section within a page, include only the anchor. 
#   For example, url: `page/#some-anchor`
#
# For more information, see:
# - Docs Site architecture: https://docs.gitlab.com/ee/development/documentation/site_architecture/
# - Global Navigation: https://docs.gitlab.com/ee/development/documentation/site_architecture/global_nav
#
# Top-level titles:
#
# Top-level titles (e.g, "Install") are also used as options for filtering search results.
# If you add, edit, or remove a top-level title, you will need to also update
# the filters in search_filters.vue. You may want to get a frontend engineer to assist with this.


# Documentation from https://gitlab.com/gitlab-org/gitlab
- title: Home
  url: ''
  submenu:
    - title: The DevSecOps platform
      url: 'devsecops'
    - title: Use of generative AI
      url: 'legal/use_generative_ai'
- title: Tutorials
  url: 'tutorials/'
  submenu:
    - title: Find your way around GitLab
      url: 'tutorials/gitlab_navigation'
      submenu:
        - title: 'Tutorial: Use the left sidebar to navigate GitLab'
          url: 'tutorials/left_sidebar/'

Merge request acceptance checklist

This checklist encourages us to confirm any changes have been analyzed to reduce risks in quality, performance, reliability, security, and maintainability.

Edited by Sarah German

Merge request reports