Have you read the Contributing Guidelines on issues?

• I have read the Contributing Guidelines on issues.

Description

This RFC aims to standardise the common request for including custom icons on cards. The goal is to make documentation card links more intuitive for readers and more aesthetically pleasing.

Instead of this:

You can have this:

Has this been requested on Canny?

https://docusaurus.io/feature-requests/p/defining-default-imageicon-lightdark-for-standalone-pages-and-categories

Motivation

The primary motivation for implementing this is that it has been requested multiple times:

• Discussed in How to set different icon for `Autogenerated` doc list #10476
• Suggested as a standard feature in Autogenerated entries: allow image override per entry #7844, but without a clear RFC
• Implemented in feat(theme): allow custom icons in DocCard component #11596, but without a clear RFC
• This Canny request likely refers to the same thing: https://docusaurus.io/feature-requests/p/defining-default-imageicon-lightdark-for-standalone-pages-and-categories

There are additional motivations to implement it:

• The current solution for implementing custom icons is quite hacky (in my opinion), requiring npm run swizzle @docusaurus/theme-classic DocCard -- --eject.
• The code required to add custom emojis is small.
• The changes proposed are entirely backwards compatible.

API design

I'll first list the API, then list all the reasons why other options were discarded.

This option introduces the option doc_card_emoji, which can be provided as an emoji to overwrite the default icon taken for the cards when using the automatic card generation with <DocCardList />. Only emojis are to be accepted on this field.

Here are the locations where this option can be added:

• Markdown front matter: The front matter accepts this option to customize the cards. Example:

---
id: croissant
title: Croissant
doc_card_emoji: 🥐
---

# Croissant

The croissant is a flaky, buttery pastry shaped like a crescent. It's made from laminated dough...

• Prop for CardLink, CardCategory (internally), exposed via prop on DocCard: allows the customization by calling the card directly, via the prop icon. This is done to respect the naming convention of the CardLayout component. This means you can also render custom emojis when calling DocCard directly from an mdx page.

Optionals to be additionally approved for more uniform behaviour (in discussion):

Optional part for the RFC: when providing the option doc_card_emoji, you can additionally set it to false to remove the icon completely from card. This should allow anyone to also add icons to the sidebar, similarly to how it is done on the plugins page. This would then be featured on both the card and the sidebar. Example:

```md
---
id: croissant
title: 🥐 Croissant
doc_card_emoji: false
---

# 🥐 Croissant

The croissant is a flaky, buttery pastry shaped like a crescent. It's made from laminated dough...

Optional part for the RFC: rename the prop on the CardLayout component from icon to emoji to prevent misunderstanding why an icon (SVG or PNG) cannot be passed (see discussion below). Since the CardLayout is not a default export, this should be feasible.

The current behaviour already splits the functionality of the card and the sidebar

I'll quote the comment from #7844 (comment):

We could add icon to sidebar items, icon in category.json, and sidebar_icon front matter in docs.

However, wouldn't this be confusing if we could only pass emojis as icons? Also, how do you control what is displayed on the generated index? My intuitive expectation would be that the icon also shows on sidebar items, and not just the generated index. Do we need to create 2 options to decouple the 2?

This is already not the case. Currently, all rendered DocCard have icons (or emojis) independent of the sidebar option.

Sidebar icons can be inconsistent if done in single items

We have tried to come up with a concept of enabling/disabling the sidebar icons independently of each other, but we have came to a couple of problems:

• Having individual icons appearing on the sidebar looks very inconsistent:

• Having the default icons appearing on the sidebar would not only break current behaviour. It also looks very inconsistent too:

Adding sidebar icons is already allowed

This has been used, for example, on the plugins page. If you include the emoji on the text, you are already able to add the icons to the sidebar:

But there are limitations, for example, the plugins have to be listed manually. If you list them via the DocCardList, they would have two emojis instead. Here is how they are currently displayed:

Enabling sidebar icons globally could be a reasonable option

Having a global option that enables icons in the sidebar would perhaps be acceptable, having this sidebar "inheriting" the card emoji.

But having a sidebar full of different emojis isn't the most aesthetically pleasing. I (personally) found the sidebar quite polluted - if the icons are all the same (defaults), the emojis serve no purpose, if they are all different, then sidebar looks inconsistent.

I'm pretty sure there are particular cases where this could be done, but as noted before you can already do it by using a custom name for the sidebar with an emoji.

As also noted, there are multiple ways to provide custom sidebar options, but this RFC focus on the simplicity of only changing the card icon.

Have you tried building it?

As mentioned, this feature has already been built in #11596, but the design has some flaws.
If it is approved, I'm willing to contribute the code.

Acknowledgements

This RFC was discussed during the 13/01 Hackergarten in Stuttgart. Special thanks to the following people:

• smillabilla
• louaybadri
• YassineRaboudi007
• sergejcodes

I hope this overview is understandable! Let me know what you guys think.

Self-service

• I'd be willing to contribute this feature to Docusaurus myself.