Skip to content

Support tabbed content on documentation pages

Sarah German requested to merge 998-tabs into main

What does this MR do and why

Adds a Vue component for creating GitLab UI tabs from a markdown doc file.

Demo pages:

How to use this

To create a tabset in a markdown file:

  1. Add {::options parse_block_html="true" /} above where the tabs will go.
  2. Add a <div class="js-tabs"> element before the first tab title.
  3. Use any regular markdown heading element for tab titles, just make sure the desired tab titles within each tabset use the same level heading.
  4. Include a {: .no_toc} under each tab title/header to omit tab titles from the table of contents in the right sidebar.
  5. Add a closing </div> at the end of the tabset.

Like this:

{::options parse_block_html="true" /}

<div class="js-tabs">

## This is the first tab
{: .no_toc}

Here's some content in tab one!

## Tab two
{: .no_toc}

Here's some content in tab two!

</div>

Here's an example: https://gitlab.com/gitlab-org/gitlab-docs/-/blob/998-tabs/content/tabs-demo/index.md

Screenshots

Example tab usage on https://docs.gitlab.com/ee/ci/#major-version-changes-breaking (on a local site)

Before After
image Jul-27-2022_13-49-58

How to test

Locally

  1. Checkout this branch on your local docs site
  2. In your docs site root dir, update dependencies: yarn
  3. Using the markdown guidelines above, edit a page in your gitlab repo (e.g, I edited /doc/ci/index.md to create the example in the gif above)
  4. In your docs site root dir, recompile the docs site: bundle exec nanoc compile
  5. Run the local web server to view site: bundle exec nanoc view
  6. Check out your tabs: http://localhost:3000/ee/ci/

Review app

  • Edit any of the pages in content/tabs-demo, then commit and push to this branch to see them in the app (we'll remove these all before merging)
  • Feel free to copy any other real pages over to this directory, try out some tabs, and commit/push back to this branch

To do

This is still a draft. Remaining tasks here:

  • Test with real content, add more demo pages
  • Test with multiple tab sets
  • Add docs (MR: gitlab!92275 (merged))
  • Add unit tests
  • TWs test with real content
  • Add linting? (maybe warn if there are too many tabs, ...?) -- let's see what comes up in testing
  • Remove the tabs-demo directory before merging

Closes #998 (closed)

Edited by Sarah German

Merge request reports