Replace remark-toc with Docusaurus-native generated index pages
#29
Comments
ptgott
added a commit
that referenced
this issue
Dec 27, 2024
Partially addresses #29 Swizzle the Docusaurus-native `DocCardList` component and adapt it to suit the Teleport docs site. Since we prefer a more text-oriented approach to components, edit `DocCardList` to return a plain `ul`, rather than tiles. Since the `DocCardList` component is a Docusaurus-native alternative to our `remark-toc` plugin, edit `remark-toc` to return a `DocCardList` instead of querying the filesystem to generate a table of contents. Once we replace all `(!toc!)` expressions with `<DocCardList />` elements, we can remove `remark-toc` entirely. Also make `DocCardList` an MDX component so docs authors don't need to add `import` statements to the top of a docs page.
ptgott
added a commit
that referenced
this issue
Dec 27, 2024
Partially addresses #29 Swizzle the Docusaurus-native `DocCardList` component and adapt it to suit the Teleport docs site. Since we prefer a more text-oriented approach to components, edit `DocCardList` to return a plain `ul`, rather than tiles. Since the `DocCardList` component is a Docusaurus-native alternative to our `remark-toc` plugin, edit `remark-toc` to return a `DocCardList` instead of querying the filesystem to generate a table of contents. Once we replace all `(!toc!)` expressions with `<DocCardList />` elements, we can remove `remark-toc` entirely. Also make `DocCardList` an MDX component so docs authors don't need to add `import` statements to the top of a docs page.
ptgott
added a commit
that referenced
this issue
Jan 3, 2025
Partially addresses #29 Swizzle the Docusaurus-native `DocCardList` component and adapt it to suit the Teleport docs site. Since we prefer a more text-oriented approach to components, edit `DocCardList` to return a plain `ul`, rather than tiles. Since the `DocCardList` component is a Docusaurus-native alternative to our `remark-toc` plugin, edit `remark-toc` to return a `DocCardList` instead of querying the filesystem to generate a table of contents. Once we replace all `(!toc!)` expressions with `<DocCardList />` elements, we can remove `remark-toc` entirely. Also make `DocCardList` an MDX component so docs authors don't need to add `import` statements to the top of a docs page.
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
We use the custom
remark-tocplugin (gravitational/docs) to generate a list of docs pages at the same directory level as the page that invokes the plugin.To invoke the plugin, a page includes the following line:
In Docusaurus, you can embed an auto-generated list of category items using the
<DocCardList />tag (see the Docusaurus docs).Let's consider using this approach to reduce the code we need to maintain.
The text was updated successfully, but these errors were encountered: