Support tabbed content on documentation pages
What does this MR do and why
Adds a Vue component for creating GitLab UI tabs from a markdown doc file.
Demo pages:
- Very basic: http://998-tabs.35.193.151.162.nip.io/tabs-demo/
- Existing page with one tab set: http://998-tabs.35.193.151.162.nip.io/tabs-demo/ci.html#major-version-changes-breaking
- Existing page with multiple tab sets:
How to use this
To create a tabset in a markdown file:
- Add
{::options parse_block_html="true" /}
above where the tabs will go. - Add a
<div class="js-tabs">
element before the first tab title. - Use any regular markdown heading element for tab titles, just make sure the desired tab titles within each tabset use the same level heading.
- Include a
{: .no_toc}
under each tab title/header to omit tab titles from the table of contents in the right sidebar. - 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 |
---|---|
How to test
Locally
- Checkout this branch on your local docs site
- In your docs site root dir, update dependencies:
yarn
- 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) - In your docs site root dir, recompile the docs site:
bundle exec nanoc compile
- Run the local web server to view site:
bundle exec nanoc view
- 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