docusaurus
docusaurus copied to clipboard
facebook
Support Level 1 title (H1) in table of contents
Have you read the Contributing Guidelines on issues?
- [x] I have read the Contributing Guidelines on issues.
Description
Currently, the setting toc_min_heading_level must be set to 2 or greater. In some markdown documents, it would be nice to a table of contents that includes level 1 (h1) titles. For example:
---
hide_title: true
---
# Part 1
## Part 1a
## Part 1b
# Part 2
## Part 2a
The default setting of toc_min_heading_level=2 could be left unchanged, so this would have no effect any current setups (validation prevents trying to set toc_min_headiner_level=1). But it would enable the option to have a table of contents use level one headers as desired.
Has this been requested on Canny?
No response
Motivation
I often use level 1 titles on my markdown documents and it would be nice for them to be able to be included in the TOC.
API design
No response
Have you tried building it?
I took a quick pass and changed the validation to allow for setting toc_min_heading_level=1 but it didn't change the generated table of contents. I poked around at packages/docusaurus-theme-common/src/utils/tocUtils.ts and it seemed like it should work for a min of 1 as well as higher, but that's as far as I got.
Self-service
- [ ] I'd be willing to contribute this feature to Docusaurus myself.
Why do you want multiple H1s? The first H1 is always going to be different from subsequent H1s because it will be used as page title, sidebar label, etc. so you are just inviting for more inconsistencies. This is a practice explicitly discouraged by both HTML and Markdown linters.
I don't think it is fair to say that the first h1 will always be used as the title and sidebar, etc. There are options (title, sidebar_label) for setting them independently. When using those options, having only a single H1 no longer is the only reasonable structure. For example:
---
title: Pets
sibebar_label: Pets
hide_title: true
---
# Dogs
Dogs are great ...
# Cats
But so are Cats
That said, if multiple H1 is discouraged by your HTML / Markdown linters this is no longer a small request to expand the allowed range of values on parameter. I think it might make sense to document somewhere that it is recommended to only have one level 1 title in Markdown (all?) pages.
Multiple HTML h1 on the same page is considered a bad practice: https://developer.mozilla.org/en-US/docs/Web/HTML/Element/Heading_Elements#avoid_using_multiple_h1_elements_on_one_page
We don't really need to document that, it's not Docusaurus specific
Markdown documents can contain more than 1 #, and either this is a good idea or not is plugin-specific.
For example if you build a slide deck using Markdown and --- separators for slides, it's fine to use one # per --- delimited section.
Docusaurus core plugins all produce a single HTML page from a single document so the HTML good practice applies here, and similarly, you should avoid using more than one #. But it doesn't mean third-party plugin authors can't implement a system where a single Markdown input produces multiple pages, similar to our slide deck example above.
So, we don't really want to document good/bad practices that are not so dogmatic and plugin-specific. It's not Docusaurus responsibility to teach you cross-cutting concerns such as HTML good practices.
It would be great if the h1 also showed up in the TOC.
For example, on a long page, the breadcrumb trail gets hidden, and it's unclear where you are within the document, especially if you're following a link from outside.
For example, before scroll:
After scroll:
