Skip to content

Add table of contents component

Sarah German requested to merge 19-toc into main

What does this MR do and why?

Adds a table of contents component.

Rather than porting over the custom ToC Vue component from the Nanoc site (code, more code, other code), this uses the Tocbot library.

A few differences from our Nanoc version:

  • Removes the vertical line on the left
  • Only includes h2-h4 (Nanoc includes h2-h6)
  • Shows h2/h3 initially; expands to show h4s when parent topic is active
  • Uses "smooth scroll" to move up/down the page to the selected header
  • Component is hidden for small-width/mobile
    • This is med/high effort to implement, but low impact since we get very little traffic from visitors using non-desktop devices. Let's consider this an enhancement to consider later on in the project. Follow-up here: #67

Closes #19 (closed)

Screenshots, screen recordings, or links to review app

Nanoc Hugo
image image

How to set up and validate locally

You should clone this project to a separate directory from your regular GitLab projects, as it will overwrite docs content files in the gitlab, gitlab-runner, etc directories at the same level.

  1. Configure a local GitLab Docs environment: https://gitlab.com/gitlab-org/technical-writing-group/gitlab-docs-hugo/-/blob/main/doc/setup.md.
  2. Check out this branch
  3. Run make setup to update dependencies
  4. Run make view to start the preview server

Visit some interior pages. All of these should show the table of contents.

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