Autogenerated entries: allow image override per entry

[ArthurFlag]

Have you read the Contributing Guidelines on issues?

• I have read the Contributing Guidelines on issues.

Description

In the current state, Docusaurus' autogenerated entries generates tiles looking like this:

Auto-generating entries is a great feature, and in my case, I'd like to use it to get scalable docs, such as listing many partners that my company integrates with.

For this, I would suggest to add the ability to customize the image that we add to the tile. Currently it's either the file or folder icon.

For example, adding this to the sidebar to specify a new image:

  {
          type: 'category',
          label: 'Essentials',
          link: {
            type: 'generated-index',
            title: 'Essentials',
            image: 'somelogopath.png'  <------- new
            description: 'my description',
            slug: 'dev/tutorials/essentials',
          },
          items: [
            'some link',
}

Or when generating tiles from a doc page with:

<DocCardList items={useCurrentSidebarCategory().items}/>

We could perhaps define the image in each entry in the sidebar.js file as well, using longhand notation:

   {
              type: 'category',
              label: 'My page',
              link: {
                type: 'doc', 
                id: 'dev/...', <------- contains the DocCardList component
              },
              items: [
               {
                  type: 'doc',
                  id: 'myDoc',
                  image: 'somelogopath.png'  <------- new
                },
              ],
            }

Has this been requested on Canny?

No response

Motivation

I need this feature for scalability reasons so this feature will happen either on my own repo, but it should ideally be a core feature as it might help other users. I can possibly get a developer to submit a PR to your repo if you can share some pointers on how to do this 'the right way'.

API design

No response

Have you tried building it?

No response

Self-service

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

[Josh-Cena]

By "image", you mean the "icon"?

You can already do so by swizzling and passing the source through customProps. It's very, very hard to design a generalizable API in this case, because most icons aren't images—they are either SVGs, React components, font awesome, or emojis.

[ArthurFlag]

that's what i meant. yes. Ok brilliant, i'll take a look at this, thanks Josh.

[smileypop]

By "image", you mean the "icon"?

You can already do so by swizzling and passing the source through customProps. It's very, very hard to design a generalizable API in this case, because most icons aren't images—they are either SVGs, React components, font awesome, or emojis.

Just saying "swizzle" it doesn't give enough information how to actually do so. Without adding any API changes, it would still be helpful to put some actual code examples in the docs how to achieve custom Link icons on autogenerated category cards.

[colinscz]

For everyone coming here. The component you have to swizzle is the DocCard component. I recommend to swizzle it with --eject in order to not modify too much of the original component.

That way in case of potential breaking changes (upcoming v3) the diff and migration effort is hopefully rather small and you can compare newer versions to your old code.

Command used: npm run swizzle @docusaurus/theme-classic DocCard -- --eject

[undergroundwires]

Hope that this can be revisted with proper official way rather than having a workaround/hack that leads to this:

[WARNING] 
Swizzle action eject is unsafe to perform on DocCard.
It is more likely to be affected by breaking changes in the future

[slorber]

@undergroundwires this is not a workaround/hack, this is the official way

You can override whatever we provide, we just want to warn you that we might have to refactor things and you'd need to adjust your code accordingly.

Unsafe might feel a bit too scary but it's perfectly fine to eject it

[slorber]

For anyone interested, I explained how to do this here: #10476 (comment)

[bvanelli]

I understand that changing this for the arbitrary image case is out of scope, but couldn't the emoji change that @slorber showed be taken as general change? As far as I can tell the original page icon is already an emoji (in this case 📄️), so it could be implemented without much effort. Is there a reasoning against it?

Here are the docs: https://docusaurus.io/docs/api/plugins/@docusaurus/plugin-content-docs#markdown-front-matter

The extra option could be called icon. The image option already exists and is used for link expansion for social media.

I would of course be willing to implement the feature and writing the documentation for it, if such feature were to be accepted.