Description above index cards

[jcubic]

Is there a simple way to add description above the cards in documentation index page?

I want to add a bit of information about this part of the documentation.

[jcubic]

I've setup a new project and found that there is a description in _category_.json file.

[slorber]

For more advanced cases you can also create a category/index.mdx and render the <DocCardList> component anywhere you want.

Doc: https://docusaurus.io/docs/sidebar/items#embedding-generated-index-in-doc-page

Examples:

• https://docusaurus.io/docs/sidebar
• https://docusaurus.io/docs/migration

[jcubic]

Thanks it seems that this is what I need, I've tried to put Markdown code into description, but it didn't work. This should solve the issue.

I've also noticed that JSX works in both mdx and md files. So it looks like mdx extension is like documentation that it contain components inside.

[slorber]

Because both extensions are currently parsed the same way as MDX for historical reasons.

But you can opt-in for CommonMark mode and use HTML tags instead of JSX, see https://docusaurus.io/docs/markdown-features#mdx-vs-commonmark

In the future .md files will be parsed as CommonMark by default. Still, we could implement the same functionality thanks to a markdown directive such as ::theme-DocCardList so that you can achieve the same with both CommonMark or MDX.