[doc,site] Consider ToC support for in-page naviagation
- Dominant language
- SystemVerilog
- Stars
- 3.6k
- Forks
- 1.1k
- Avg merge
- 2d 22h
- Merged PRs (30d)
- 141
Description
### Description
The new mdBook docs structure gives more opportunities to split-up content into sub-pages and nested page structures to convey a hierarchy of information. However, an excessive number of pages would hinder the readers experience, and we need to consider the in-page navigation options.
A table-of-contents within a page is a good option for longer pages that do not make sense to further split-up.
Possible technical solutions to explore could be :
- https://github.com/badboy/mdbook-toc
- https://github.com/slowsage/mdbook-pagetoc
- A custom solution / script e.g. https://medium.com/@acrodriguez/one-liner-to-generate-a-markdown-toc-f5292112fd14
Contributor guide
Research direction
Start by comparing the mdbook-toc and mdbook-pagetoc approaches linked in the issue, along with the proposed custom Markdown TOC script. Determine which approach fits the existing mdBook site and define completion as an agreed in-page table-of-contents solution for longer pages.
Written by the indexing model from the issue text.
Assessment
- Tech stack
- markdown
- Domain
- documentation
- Issue type
- Documentation
- Difficulty
- 5/5
- Estimated time
- Over a week
- Activity status
- Stale
- Clarity
- Needs clarification
- Newbie friendliness
- 25/100