search

gravitational / docs

Source code backing goteleport.com/docs
https://goteleport.com/docs
Apache License 2.0
11 stars 13 forks source link

Generate docs sidebar sections automatically #480

Closed ptgott closed 1 week ago

ptgott commented 1 week ago

Add a config.json field within each navigation entry called generateFrom. This designates a relative path from docs/pages from which to generate entries within the sidebar.

When generating pages, a function called generateNavPaths looks for pages to use as second-level section introductions. These can either be called introduction.mdx or have the same name as a second-level subdirectory.

Adding a generateFrom field is consistent with the Docusaurus approach to sidebar generation, in which a configuration field indicates which directory to generate a section from. This gives us control over the title and icons we use for navigation sections, which aren't available to fetch from a directory tree alone. It also lets us use the current, hardcoded entries approach for some sections if we need to.

Also un-skips some accidentally skipped tests.

vercel[bot] commented 1 week ago

The latest updates on your projects. Learn more about Vercel for Git ↗︎

Name Status Preview Comments Updated (UTC)
docs ✅ Ready (Inspect) Visit Preview 💬 Add feedback Jul 1, 2024 7:20pm
ptgott commented 1 week ago

@avatus I've reworked this a little bit to change the expectations for subdirectory pages. I've added the expectation from Docusaurus that a category page have the same title as the parent directory (docs). Docusaurus also allows category pages to be called index.mdx and README.mdx, but Alexey advised against using index.mdx for non-root pages and README.mdx doesn't seem appropriate.