feat(content-docs): sidebar category linking to document or auto-generated index page

[slorber]

Breaking changes

Doc index slugs

Docs with the following filename patterns now have better urls/slugs:

• docs/dir/subdir/index.md => slug becomes /docs/dir/subdir/ instead of /docs/dir/subdir/index
• docs/dir/subdir/readme.md => slug becomes /docs/dir/subdir/ instead of /docs/dir/subdir/readme
• docs/dir/subdir/subdir.md => slug becomes /docs/dir/subdir/ instead of /docs/dir/subdir/subdir

You can revert to the former behavior easily with frontmatter: slug: /dir/subdir/index

---

Motivation

• Ability to link a sidebar category to a category introductory doc
• Ability for auto-generated sidebars to use filename conventions (such as index.md) as category introductory doc
• Ability to auto-generate a category index from its subitems

See also #2643

Not included

The following were considered but are not part of the current PR (may eventually come later):

• Add a link: {type: "firstDoc"} shortcut to automatically link the category to its first child doc
• Ability to add a generated-index link to all categories by default as a plugin option
• Assign a default slug/path to a sidebar category (canny)

Have you read the Contributing Guidelines on pull requests?

yes

Test Plan

Unit tests, snapshots and dogfood on website

Test urls:

• https://deploy-preview-5830--docusaurus-2.netlify.app/docs/next/category/getting-started
• https://deploy-preview-5830--docusaurus-2.netlify.app/docs/next/category/guides
• https://deploy-preview-5830--docusaurus-2.netlify.app/docs/next/markdown-features/
• https://deploy-preview-5830--docusaurus-2.netlify.app/tests/docs/category/tests

Docs:

• Category links (doc, generated-index)
• Category index.md convention
• docCategoryGeneratedIndexComponent option

[github-actions]

Size Change: +11.8 kB (+2%)

Total Size: 656 kB

Filename	Size	Change
website/.docusaurus/globalData.json	40.1 kB	+1.83 kB (+5%)	🔍
website/build/assets/css/styles.********.css	101 kB	+1.51 kB (+2%)
website/build/assets/js/main.********.js	485 kB	+8.47 kB (+2%)

ℹ️ View Unchanged

Filename	Size
website/build/index.html	29.5 kB

_{compressed-size-action}

[Josh-Cena]

Is it really desired to have autogenerated category index pages? Should we add a config option and default it to false?

---

It's interesting because I see discussion going around for a year, but seems we never settled down on an API design. Here's what I envision:

• A new category item option indexPage that accepts a doc ID;
• Port this option to category metadata;
• Carefully design the UX to differentiate between "clickable" and "non-clickable" categories.

I'm skeptical about the autogenerated category index pages. Just like the blog archive, it's not going to be very polished, and very opinionated update: I think the current design is quite good. We aren't fully unopinionated anyways. I'm also not sure if index.md or README.md should automatically become category index pages.

There's also #2537 which concerns routing instead of sidebar generation, but I think we should stay unopinionated and don't do these magic under the hood. Users can use slug to manually set the URL, and use indexPage to make any page the category index, but Docusaurus shouldn't apply magic defaults.

[slorber]

😅 this is a draft to have something working locally and explore the problem space and UX possibilities. We'll figure out later how to make it configurable and what the API should look like, it's not in a state worth reviewing for now.

[Josh-Cena]

I personally is quite clueless about how to differentiate between "linked" categories and "non-linked" ones :P Maybe we should just make the "non-linked" ones non-clickable as well so they don't look like links at all? Good luck👍

[netlify]

✔️ [V2]

🔨 Explore the source changes: 2daa173

🔍 Inspect the deploy log: https://app.netlify.com/sites/docusaurus-2/deploys/61a9f0d5bb198c000728c6f8

😎 Browse the preview: https://deploy-preview-5830--docusaurus-2.netlify.app

[github-actions]

⚡️ Lighthouse report for the changes in this PR:

Category	Score
🟢 Performance	95
🟢 Accessibility	98
🟢 Best practices	100
🟢 SEO	100
🟢 PWA	95

Lighthouse ran on https://deploy-preview-5830--docusaurus-2.netlify.app/

[Josh-Cena]

...is that really future-proof? Or is it only temporary?

[slorber]

😅 definitively a shitty temp workaround but better than having the wrong link :p

documented it here: #6041

[Josh-Cena]

Maybe we should have a hook like useVersionLink? 🤔

[slorber]

I don't know, if possible I'd prefer to let users keep using regular markdown links than using hooks in their docs

[slorber]

Yes, I understand your concern, it also can be confusing. But on the other hand, a "regular" list item doesn't need a wrapper, then why add one for it? It is double-edged sword, or simplicity vs consistency, and I'd like to have both at the same time, but that can't always be achieved, and at times such compromises had to be made.

In general, I'd rather have simplicity in our codebase and userland CSS selectors instead of the simplicity of the HTML structure

However if you want, I can do new PR in Infima repo, and add wrapper to all list items, also might need to change styles, but is it really necessary?

I don't feel like the current solution is bad and I'm going to merge it as is for now to not delay this PR even more. If you want to keep improving we can do that in another PR before the next release.

After all, category index items will be much smaller than regular list items in most cases, so it seems kind of redundant to have that wrapper for all items.

Not sure to understand what you mean here 🤔

[lex111]

I just don't like to have additional HTML elements/wrappers where they are not needed at all, as in this case with regular menu list items. So for now, I prefer to leave it as it is. 2021-12-03 13:02 GMT+03:00, Sébastien Lorber ***@***.***>:

…

> Yes, I understand your concern, it also can be confusing. But on the other > hand, a "regular" list item doesn't need a wrapper, then why add one for > it? It is double-edged sword, or simplicity vs consistency, and I'd like > to have both at the same time, but that can't always be achieved, and at > times such compromises had to be made. In general, I'd rather have simplicity in our codebase and userland CSS selectors instead of the simplicity of the HTML structure > However if you want, I can do new PR in Infima repo, and add wrapper to > all list items, also might need to change styles, but is it really > necessary? I don't feel like the current solution is bad and I'm going to merge it as is for now to not delay this PR even more. If you want to keep improving we can do that in another PR before the next release. > After all, category index items will be much smaller than regular list > items in most cases, so it seems kind of redundant to have that wrapper > for all items. Not sure to understand what you mean here 🤔 -- You are receiving this because you were mentioned. Reply to this email directly or view it on GitHub: #5830 (comment)

[slorber]

So for now, I prefer to leave it as it is.

Great, so let's keep it as it is then 👍

---

Awesome, so it seems this PR is ready, thanks for the help 👍

[marcusnewton]

I've suggested an API for configuring type: "autogenerated" categories, so users can specify what conventions their markdown folder is intended to support.

e.g. if you have docs/Guides/Guides.md but don't want Guides to be a category link with Guides.md content, you could do this:

items: [
  {
    type: "autogenerated",
    categoryLinkIndex: true,
    categoryLinkReadme: true,
    categoryLinkSameName: false,
  },
],

https://docusaurus.canny.io/feature-requests/p/allow-disabling-globally-the-category-index-link-convention

[slorber]

Totally agree @marcusnewton , this is one of a new configuration that I think we should add once we have figured out a good public API

For now the code is:

// By convention, Docusaurus considers some docs are "indexes":
// - index.md
// - readme.md
// - <folder>/<folder>.md
//
// Those index docs produce a different behavior
// - Slugs do not end with a weird "/index" suffix
// - Auto-generated sidebar categories link to them as intro
export function isConventionalDocIndex(doc: {
  source: DocMetadataBase['slug'];
  sourceDirName: DocMetadataBase['sourceDirName'];
}): boolean {
  // "@site/docs/folder/subFolder/subSubFolder/myDoc.md" => "myDoc"
  const docName = path.parse(doc.source).name;

  // "folder/subFolder/subSubFolder" => "subSubFolder"
  const lastDirName = getLastPathSegment(doc.sourceDirName);

  const eligibleDocIndexNames = ['index', 'readme', lastDirName.toLowerCase()];

  return eligibleDocIndexNames.includes(docName.toLowerCase());
}

I was thinking about exposing a similar function in the docs plugin config options (maybe a simpler interface). Do you really need the granularity of defining those rules on a category level, or it can be more global?

I don't like much introducing 3 booleans for that, maybe we should have a way to specify file globbing patterns 🤷‍♂️

[marcusnewton]

@slorber I can definitely work with global config, but not sure if others might want to reintroduce this automatic category linking for certain paths in their tree.

[marcusnewton]

Glob pattern sounds nice

[KatherineWhan]

This functionality is great. Is there any chance it will be extended to be able to link to a page in src/pages? I have already created landing pages for my category folders with tiles and filter components that I would like to be able to link to directly. Thanks.

[slorber]

This functionality is great. Is there any chance it will be extended to be able to link to a page in src/pages? I have already created landing pages for my category folders with tiles and filter components that I would like to be able to link to directly. Thanks.

Thanks @KatherineWhan

I don't understand what you are trying to do.

There's a "link" sidebar item already allowing you to link to any standalone page if you want, and due to our plugin architecture the pages, docs and blogs don't know about each others.

If you really want the category link to target a standalone page, you can try to add your tiles and filters to a doc using MDX

[Josh-Cena]

@slorber it would just be link: {type: 'link', to: '/intro'}, IMO

[slorber]

@slorber it would just be link: {type: 'link', to: '/intro'}, IMO

If the intro is a standalone page, this means the sidebar will disappear and we are leaving the docs plugin. I'd like to understand the motivation to do so: having a mockup of the landing page, what are the tiles and their links, why it's better to hide the docs sidebar in such case etc.

Not sure why I can't access the Supabase docs atm (probably my network 🤷‍♂️ ) but afaik it had tiles on some pages and they are nicely integrated, and still display the docs sidebar: https://supabase.io/docs/

[Josh-Cena]

Yeah, the sidebar disappearing point makes sense. However it's not the only case that can happen: a regular link item can cause this as well, without displaying the external link icon. Still yes I feel like this feature request is underexplained. @KatherineWhan you can open another feature request issue, detailing your API design and desired effects.

[KatherineWhan]

Hi @Slober and @Josh-Cena

Thanks for your responses. Yes, essentially what I was trying to do was link: {type: 'link', href: '/pagename} where the page that displays does not display the sidebar.

We have now had another look at the functionality and decided to add my component to a doc, include the sidebar and link it with link: {type: 'doc', id: 'docName'}, as I can now use the hideableSidebar: true, to improve the screen realestate for my 80+ tiles and search filter.

I have one other question about the sidebar category linking (that I'm hoping that you can answer that I couldn't find in the help). If you have a link to a doc for category where the items are autogenerated, is there any way to stop the linked doc from displaying twice? It displays once as the file linked to the folder and once wherever it is in the folder of items. For example:

{
      type: 'category',
      label: 'Knowledge Base',
      link: {type: 'doc', id: 'kb/overview'},
      items: [
        {
          type: 'autogenerated',
          dirName: 'kb', 
        },
      ],
    },

Displays as:

Knowledge Base (Overview page displays)
|_article 1
|_article 2
|_article 3
|_Overview

Thanks again for your help! :)

[Josh-Cena]

Yes, we have quite a few people complaining about this. We will let you declare a list of subitems to be excluded from the autogenerated slice.