Category auto-generated index page should support custom category/link descriptions

[Dr-Electron]

Have you read the Contributing Guidelines on issues?

• [X] I have read the Contributing Guidelines on issues.

Description

If you use index pages and your sidebar contains a link it would be nice if you could either:

• Add a description to the link by doing something like: { type: 'link', label: 'Facebook', // The link label
  href: 'https://facebook.com', // The external URL
  description: 'Some description' },

or

• Fetch the data from the linked page if possible. This may be very specific to our use case but we link from one docs plugin to another in our Wiki as we can't always use relative links. So it would be nice if the index page could somehow get the frontmatter from the linked page.

Wdyt?

Has this been requested on Canny?

No. I can't login there because of some unknown error

Motivation

We would like to work more with index pages but we use a lot of links in the sidebar and that just don't really look nice.

API design

No response

Have you tried building it?

I didn't try to build it myself. Not sure what the best way would be yet. So maybe let's discuss first what would be possible.

Self-service

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

[slorber]

What I understand is that you want this to display in a better way

That seems reasonable to add a sidebar link attribute to provide a link description

Fetch the data from the linked page if possible. This may be very specific to our use case but we link from one docs plugin to another in our Wiki as we can't always use relative links. So it would be nice if the index page could somehow get the frontmatter from the linked page.

---

I doubt we'll want to implement this. Instead we should allow you to use top-level async/await in sidebars.js.

        {
          type: 'link',
          href: 'https://facebook.com',
          label: await fetchLabel(),
        },

Unfortunately, this is blocked by https://github.com/sindresorhus/import-fresh/issues/22 so this will come later. In the meantime, you can use sync FS calls if the data is available locally

[heysujal]

@slorber Hi, I want to work on this issue , but I am new to this project. Can you guide how can I go about implementing this ?

[slorber]

Hey @heysujal, this is a very simple issue but it requires being used to Docusaurus in the first place to understand what should be done. If it's not the case, I'd recommend becoming first familiar with Docusaurus and only then trying to contribute. We have an active discord channel in case you are looking for help.

[YashasviChaurasia]

@slorber @Dr-Electron @dreiss I would like to work on this issue. Thank you

[slorber]

go ahead then

[slorber]

Similarly, we want to support custom category descriptions

See https://github.com/facebook/docusaurus/discussions/7985

[alliyya]

Would be nice to also support custom icons too, or add that as an option in the front matter of docs in general.

[slorber]

Would be nice to also support custom icons too, or add that as an option in the front matter of docs in general.

It would be weird to allow you to provide a custom icon as frontmatter. Custom icons are not only emojis like we used there, but can also be svgs, images, react components... The best way to provide custom icons atm is with swizzling, and we'll make this easier

[ZarakiKanzaki]

Hi @slorber ! I wanted to ask you a few questions. As far as I'm understanding the thread it seems there were multiple requests, the one that seems not to be completed is this following one, isn't it?

Similarly, we want to support custom category descriptions

See #7985

If so, I would love to contribute to this issue 😊

[slorber]

@ZarakiKanzaki we need a description on:

• category link in sidebars.js
• _category_.json files for autogenerated sidebars
• category items of type link (see https://github.com/facebook/docusaurus/issues/7818#issuecomment-1193840525)

Go ahead and open a PR then. As you can see people want to work on it but then go silent, so we don't claim issues anymore and just open the PR directly. Once the PR is open we can chat more about the details in it.

[ZarakiKanzaki]

@ZarakiKanzaki we need a description on:

• category link in sidebars.js
• _category_.json files for autogenerated sidebars
• category items of type link (see Category auto-generated index page should support custom category/link descriptions #7818 (comment))

Go ahead and open a PR then. As you can see people want to work on it but then go silent, so we don't claim issues anymore and just open the PR directly. Once the PR is open we can chat more about the details in it.

Thank you for your quick reply 😊 I'll try to open a PR asap

[Jaya-sys]

Hey can you assign this issue to me?

[ZarakiKanzaki]

Go ahead and open a PR then. As you can see people want to work on it but then go silent, so we don't claim issues anymore and just open the PR directly. Once the PR is open we can chat more about the details in it.

@Jaya-sys FYI

[slorber]

Something else to address likely in the same PR @ZarakiKanzaki: https://github.com/facebook/docusaurus/issues/7598

If a category has a link to a doc, and that category doesn't have a "description" attribute, we can use the linked doc's frontMatter.description as a fallback value

[pke]

@slorber would it also be possible to provide an image to the auto-generator from within the doc that is then displayed in the index box for each page in a fixed size?

[slorber]

@pke any prod doc example or mockup to share?

How such image should be provided, and displayed?

Does something prevent you from implementing this with swizzle+customProps, and deploy to prod, so that we can learn from your live code + design?

[pke]

If you @slorber could point me to a doc about this swizzle+customProps pattern I would certainly give it a try. As context: We need to document the internal workings of our app and we would like to put a screenshot of the app screen first into each category.

So the screenshot could be supplied via front-matter or be just the first image tag, that is encountered (much like the category text is extracted from the first paragraph)

[slorber]

@pke each docs sidebar item allows passing arbitrary data as a customProps attribute: https://docusaurus.io/docs/next/sidebar#passing-custom-props

This data is injected into the relevant sidebar item components as props too, so if you swizzle and theme component responsible for rendering a sidebar item, you can use that data here.

The components that render sidebar items include:

• the... sidebar items themselves
• the docs breadcrumb
• the category index page

I would suggest to assign sidebarCategory.customProps.myImage in your sidebar config, and then swizzle DocCard to display that custom image. DocCard is the component used on the category index page.

If you are using auto-generated sidebars it should work to declare customProps directly from the _category_.json file

[slorber]

Basic support for category/link description through the sidebar file (not autogenerated) was added in https://github.com/facebook/docusaurus/pull/8236 and will be in Docusaurus v2.4

This issue remains open to add support for other cases.

---

Note: I think we should also allow description on doc/ref items?

Also it looks like it's not possible to override docs sidebar_label by using a custom label on the sidebar file. I think the sidebar file should win over frontmatter for such label (and future description) because a doc can be referenced twice in a sidebar (although we highly recommend users to use refs for that case)

[KirtiKamal]

Similarly, we want to support custom category descriptions

See #7985

Hey i am new to opensource and want to contribute to this what actually want to change in this. You want to remove that 4items with custom texts right?