Skip to content

docs: avoid hiding content in section index pages, de-dupe project spec overview#345

Open
awphi wants to merge 2 commits into
mainfrom
avoid-hidden-index-pages
Open

docs: avoid hiding content in section index pages, de-dupe project spec overview#345
awphi wants to merge 2 commits into
mainfrom
avoid-hidden-index-pages

Conversation

@awphi

@awphi awphi commented Jul 16, 2026

Copy link
Copy Markdown
Contributor

Background

One of my pet peeves with docusaurus is its default behaviour to render the content of index.md or README.md in subdirectories as a page tied to the section heading of that subdir.

For example, currently our introduction/README.md content is rendered under this clickable 'Overview' section heading:

Screenshot 2026-07-16 at 15 18 50

Imo, this harms discoverability of important overview content. Now take a look at (again, imo) a couple of good docs sites with docusaurus-like sidebars:

None of them do this! I prefer the cleanliness of the site feeling like a directory of files and avoiding the directories holding content of their own.

Changes

  • Sets some docusaurus metadata in _category_.json files to avoid the gripe outlined above.
  • Deletes the 00-overview.md page of the project specification. It felt there was not useful content on there not covered in the README and having two overview/introduction type pages was a bit odd. Lmk if you disagree!

Old sidebar (section headings are clickable and contain README.md content):

Screenshot 2026-07-16 at 14 58 41

New sidebar (section headings are not clickable!):

Screenshot 2026-07-16 at 16 20 38

Checklist

  • 🤖 This change is covered by tests as required.
  • 🤹 All required manual testing has been performed.
  • 📖 All documentation updates are complete.

Signed-off-by: awphi <26072111+awphi@users.noreply.github.com>
@awphi
awphi requested a review from a team as a code owner July 16, 2026 15:22
Signed-off-by: awphi <26072111+awphi@users.noreply.github.com>
@awphi awphi changed the title docs: avoid hiding content in section index pages docs: avoid hiding content in section index pages, de-dupe project spec overview Jul 16, 2026
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

2 participants