lowRISC / lowRISC/opentitan

[doc,site] Consider ToC support for in-page naviagation

Open
#17,623 1 comment 0 reactions 0 assignees View on GitHub
Component:Doc Earlgrey-PROD Triaged
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

Open the contributing 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

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.