Docusaurus: Auto generate sidebar according to the docs folder structure

[felipecrs]

🚀 Feature

Auto generate sidebar according to the docs folder structure.

Have you read the Contributing Guidelines on issues?

Yes

Motivation

For me, it seems to be redundant to manage both the sidebars file and the docs folder structure, since the sidebars can be inferred from it.

Also, every time I add a new md file, I have to add it to the sidebar. This might not be a problem for fully manual work, but it's a problem when the md files can be generated automatically so we don't know beforehand what would be their IDs.

Pitch

Let's consider a docs folder like this:

- README.md
- api/
  - a.md
  - b.md
- cli/
  - a.md
  - b.md

We would need to set a sidebars like that to properly show this:

module.exports = {
  "sidebar": [
    "README",
    {
      "type": "category",
      "label": "API",
      "items": [
        "api/a",
        "api/b",
      ]
    },
    {
      "type": "category",
      "label": "CLI",
      "items": [
        "cli/a",
        "cli/b"
      ]
    }
  ]
};

This could be inferred automatically rather than requiring the user to maintain a separate file. Further customizations could be made through Front Matter in each doc. In case a folder requires personalization, a README.md could also be created for it.

[fanny]

We could have the both options. It seems a good proposal for me.

[slorber]

Hi

Will be back from holidays on Monday 28.

How do we keep retro-compatibility?

Also what if we want b before of a?

Le mar. 22 sept. 2020 à 19:37, Fanny [e-mail] a écrit :

We could have the both options. It seems a good proposal for me.

—
You are receiving this because you are subscribed to this thread.
Reply to this email directly, view it on GitHub
https://github.com/facebook/docusaurus/issues/3464#issuecomment-696905495,
or unsubscribe
https://github.com/notifications/unsubscribe-auth/AAFW6PSIWD3426Q7NA43ELTSHDVHJANCNFSM4RSX5DOA
.

[felipecrs]

How do we keep retro-compatibility?

If this ends up with a new option in the docusaurus.config.js, such as inferSidebarsFromFolder, we could simply make it default to false.

Also what if we want b before of a?

Perhaps prefixing numbers in the files: 1-b.md, 2-a.md.

[slorber]

Perhaps prefixing numbers in the files: 1-b.md, 2-a.md.

Why not, but you'd rather add slug frontmatter to have nice url paths

I guess the category labels should be inferred from the folder names. So this means folder names should also have a number prefix for ordering.

That also means it's not possible to have docs without sidebar, nor multiple sidebars, nor refs or external links in sidebars, so this option is limited compared to have a proper sidebars file.

---

Wonder if it's really worth it. It may as well be quite confusing and add some complexity for no real gains except replacing centralised config boilerplate by number prefixes and frontmatter boilerrplate.

Do you really see yourself using such a feature? If so, I'd like to ask you a commitment first.

For example:

• show me a Docusaurus site with a sidebars file (browsable online + github repository).
• make a git branch and show me the exact docs FS structure and frontmatter you'd like to use to be able to get the first site running without the sidebar (I don't expect the site to be running obviously, as the feature is not implemented)

[arinthros]

I wrote a script for one of our monorepos that generates markdown from jsdoc comments, keeping the folder structure, and then auto-generates the sidebars.js while preserving any custom entries. It needs a few tweaks like alphabetizing and removing non-existent files, but it should give you a starting point for your project.

https://gist.github.com/arinthros/526df3ef12383d26903c1c8588211cca

The sidebar structure looks like this

- General Info
- Package One
  - Custom Doc
  - API Reference (auto generated folder)
    - someFunction
    - anotherFunction
- PackageTwo
  ...

[felipecrs]

@arinthros Sounds very cool!

Just to mention, the docusaurus-plugin-typedoc also does that. And this is how I use it:

https://github.com/felipecrs/megatar/blob/master/website/sidebars.js#L5

The plugin generates the typedoc-sidebars.js file, then I import it from my sidebars.js.

Result: https://felipesantos.dev/megatar/api/

[felipecrs]

I guess the category labels should be inferred from the folder names. So this means folder names should also have a number prefix for ordering.

Not only. As per my initial proposal, further customizations for the categories could be made through an index.md in the root of each folder/category.

That also means it's not possible to have docs without sidebar, nor multiple sidebars, nor refs or external links in sidebars, so this option is limited compared to have a proper sidebars file.

I was not thinking this way. I think we must add this feature in a way that you are free to use both methods (manual or auto-generated sidebars). Something like:

// sidebars.js
module.exports = {
  sidebar: [
    "introduction",
    "API": './api/'
  ]
} 

Notice that in API category, I referenced a folder, this means it's supposed to be auto-generated. But probably we think of a more clean way.

Do you really see yourself using such a feature? If so, I'd like to ask you a commitment first.

Yes, but I totally understand that you should not waste time to implement a feature if you have a single user. Perhaps some kind of votation could help? (I'm just imagining)

show me a Docusaurus site with a sidebars file (browsable online + github repository).

https://felipesantos.dev/megatar
https://github.com/felipecrs/megatar/tree/master/website

Not a production-grade example though.

make a git branch and show me the exact docs FS structure and frontmatter you'd like to use to be able to get the first site running without the sidebar (I don't expect the site to be running obviously, as the feature is not implemented)

The master branch is already a good example:

- docs
  - index.md # auto-generated by website/scripts/import-readme.md
  - api # auto-generated by docusaurus-plugin-typedoc
    - globals.md
    - Classes
      - Image.md
      - SaveImage.md

The sidebars labels are already customized because of the title Front Matter in each of the files.

[slorber]

Thanks for the infos.

I need to work on i18n, not sure there's a huge need for this right now, and we need to figure out a good API surface for this feature first, so unless someone wants to help design/implement this will wait, but we can keep the discussion about API design.

An idea could be to use a special kind of category type, somehow quite similar to your proposal but maybe more explicit.

module.exports = {
  docs: [
    {
      type: 'autogenerated',
      label: 'Docusaurus',
      folderPath: './docs/docusaurus'
    },
  ],
};

---

One important thing to consider is that it should work well with versioning. If we copy the sidebars.js to the versioned folders, it should still work so we should avoid relative paths/imports in this sidebars file, so creating "utils" to generate a sidebars slice from a relative path is likely not a good idea (related to https://github.com/facebook/docusaurus/issues/3285#issuecomment-691086254).

[felipecrs]

Awesome, your design is more refined than what I proposed. LGTM.

[Clindbergh]

An idea could be to use a special kind of category type, somehow quite similar to your proposal but maybe more explicit.

module.exports = {
  docs: [
    {
      type: 'autogenerated',
      label: 'Docusaurus',
      folderPath: './docs/docusaurus'
    },
  ],
};

Above example would be generated from this directory:

Docsaurus/
├─ intro.md
├─ design.md
├─ contribute.md

[tree credits], where all .md files have a title set, correct?

If later Design Principles itself becomes a folder (which will be then be an autogenerated category), e.g.

Docsaurus/
├─ intro.md
├─ design-principles/
│  ├─ kiss.md
├─ contribute.md

or if the category is an i18n name or something like Why Docsaurus?, we have a problem. Thus, I suggest to a _category_.md (like __init.py) file defining how the details of the category, e.g.

Docsaurus/
├─ _category_.md
├─ intro.md
├─ design-principles/
│  ├─ _category_.md
│  ├─ kiss.md
├─ contribute.md

This would make the Docs only mode much more useful.

[vthirupathi]

has anyone begun work on this? I'd like to take a look myself

[slorber]

Sure please do, thanks

Le jeu. 12 nov. 2020 à 21:15, vthirupathi [e-mail] a
écrit :

has anyone begun work on this? I'd like to take a look myself

—
You are receiving this because you commented.
Reply to this email directly, view it on GitHub
https://github.com/facebook/docusaurus/issues/3464#issuecomment-726316318,
or unsubscribe
https://github.com/notifications/unsubscribe-auth/AAFW6PW4J64M6T457NPRSYLSPQ663ANCNFSM4RSX5DOA
.

[rudasn]

+1 for this feature.

The use case is that docusaurus docs are autogenerated, and keeping track of said files in the sidebar file will surely lead to issues.

What I did to resolve this issue, is have a separate script (eg. guides-sidebar.js) that picks up md folders and files from a given directory (eg. website/guides) and generates a compatible sidebar that can be required from the main sidebars.js files (or used as a separate sidebar in another top-level page).

This way I can choose when and how to use the generated sidebars, and no other configuration is required.

Implementation details:

• How to determine sorting order? By using a new properly on the frontmatter of markdown documents, sidebar_sort_order.

• How to define a name for you category? By using a new property, sidebar_category, on the first markdown file of the category in question (first markdown, after sorting by sidebar_sort_order). This can also be achieved by having a special _category.md file that provides frontmatter properties for the category.

• How to define the sort order of the category? Same as naming a category, by using a new property, sidebar_category_order, on the first markdown file of that category.

Here's an example implementation: https://gist.github.com/rudasn/e4f501cdfa7e066e4a4ecf7804a10894