DocCards showing a category which has an associated doc should show that doc's description (used in generated-index)

[andrewnicols]

Have you read the Contributing Guidelines on issues?

• I have read the Contributing Guidelines on issues.

Prerequisites

• I'm using the latest version of Docusaurus.
• I have tried the npm run clear or yarn clear command.
• I have tried rm -rf node_modules yarn.lock package-lock.json and re-installing packages.
• I have tried creating a repro with https://new.docusaurus.io.
• I have read the console error message carefully (if applicable).

Description

When showing a generated-index, or manually showing the DocCardList, a DocCard representing a Category where that category has an associated link or _category_.* should use the description associated with either of those items rather than just listing the number of items within it.

Reproducible demo

https://docusaurus.io/docs/category/guides

Steps to reproduce

1. See https://docusaurus.io/docs/category/guides
2. Note that the "Docs" category has four immediate children, but no description
3. View the Docs category

• Note: This is a document, with a usable description which would be more useful in the DocCard

Expected behavior

A useful description is shown

Actual behavior

The number of child documents is shown

Your environment

N/A

Self-service

• I'd be willing to fix this bug myself.

[slorber]

@andrewnicols what I understand:

We have a page "Docs Introduction": https://docusaurus.io/docs/docs-introduction

It has a description (here inferred from content, but it does not matter): "The docs feature provides users with a way to organize Markdown files in a hierarchical format."

This page is used as a sidebar category link.
And the parent category has a generated index.

So you want the description to display there instead of the number of items?

---

That looks like a reasonable thing to do.

Should this be configurable?

Docs description is inferred so normally very often present, do we still need to display a count in some cases (as a fallback?)

Do we always want to show the description (and not the doc title? which may be the same as the category name 🤷‍♂️ )

[sam-bryant]

I'm encountering this issue as well. I don't want to comment as to the amount of configurability that's built. I'm essentially after the description.

I've also noticed that the card text has a length of one line. It gets truncated with ... It might be nice to allow for a few lines of text for a card. Maybe that could be configurable.

And while I'm at it, to be honest, it would be pretty sweet to be able to assign a custom icon. That being said, I would consider it a much lower priority.

[slorber]

Related to #7818 where we allow a category to have a description. Will make sure that if the category links to a doc, we'll fallback to that doc description.

Pending PR likely to implement this: #8236

---

@sam-bryant regarding the card design, that's a different subject for which we'd rather have a dedicated feature request. Note you can swizzle the DocCard component to add the line length you want and custom icons.

There's no way we'll provide good-enough config options that would fit the subjective tastes of all users, and swizzling will remain the solution that we encourage you to adopt for such use-cases.