Allow customizing category description in generated-index cards
complete
V
Vlasta Pavicic
We love the look of the generated-index cards but we would find it very useful if we could use them as adjustable components on a regular page.
That way we could create overview pages that could have an introduction text followed by the index cards. It would be awesome if the description in the card could be customizable bcs, not all first sentences are a great description of the pages they link to. It would also enable us to replace a count of items with a description of what the pages contain.
There would always be 2 cards of the same width in one row, but the height of the cards would be influenced by the card with more lines of text (for example, if the left card has 3 lines of text, the right card with 2 lines of text would match the height of the left card and vice versa).
Thank you!
Joshua Chen
complete
You can now do this with swizzling DocCard and using customProps.description.
https://github.com/facebook/docusaurus/pull/6780
We will later add a POC on our own website
V
Vlasta Pavicic
Thank you for your guidance and the further inspection of the proposed feature! :)
Joshua Chen
under review
Hi! Your feature request can be broken down into several parts.
- About the description text of doc cards. You can provide description as front matter instead of using the default excerpt. https://docusaurus.io/docs/api/plugins/@docusaurus/plugin-content-docs#description
- About the description of categories. This is the only part that I think we can inspect further, because AFAIK there's currently no way to set this text on a generated index page.
- About reusing doc cards on any page. We now document this usage here: https://docusaurus.io/docs/next/sidebar/items#embedding-generated-index-in-doc-page And note that the component accepts any kind of itemsas long as it has the correct shape: you can filter, insert, or modify any item in this list.
MikeMc
Joshua Chen: Hi Josh! This post was very helpful. Note on your point 3 - it looks like you can only use that solution if the page is the category. It would be useful to be able to easily input an arbitrary directory instead of only the current directory.
Joshua Chen
MikeMc: That was both a deliberate design decision and a technical limitation. There's no way to uniquely identify a category, therefore it's impossible to unambiguously "input an arbitrary directory". Also, it doesn't make sense to put an overview anywhere that's not the category index, and we build an opinionated tool, so we get to decide the best practices for you. However, the entire sidebar is available as global data, so if you really want, you can traverse it yourself. The hook you use is
usePluginData
: https://docusaurus.io/docs/next/docusaurus-core#usePluginDataMikeMc
Joshua Chen: thanks for the response Joshua Chen! i can think of a few situations where you would want to have categories defined outside of the structure. but like you said, this is an opinionated tool so i guess i can live with it or build my own thing :)