Sidebar Customisation

[mghill]

Due to the verdict that file structure and URL should match, and be very simple, we should enrich the sidebar.

It would be very messy to require an edit to docs-site to manually update the sidebar whenever there's a new page (or subsection etc) in Docs, the ideal solution is a way to direct the process from the docs, and frontmatter is the place that makes the most sense.

The sidebar could be generated from a "path" given to it in the frontmatter. It looks like the default behaviour is to generate a sidebar from a directory path, and also that a doc's place in the sidebar can be affected by lines in the frontmatter. So this solution feels doable, and maintainable within the docs themselves.

Limitations (with management strategies):

• If you want to do a bulk change, you need to do it doc by doc (uncommon case)
• By defining it doc-to-doc there is a risk that it is "wrong" on a given doc, rather than having it defined at a central location & applied to all docs - could have unexpected behaviour such as having two folders, named "Key Concepts" and "key-concepts" (given the branch and PR process, I expect any issues with this would be caught, rather than going live)
• If you want a doc to appear multiple times in the sidebar - which is a cool feature I'd like to use - I can't see a simple way to indicate that from the frontmatter, other than simply having many "sidebar_slug" (or whatever) entries for each location you want it to appear.

[kimburgess]

For handling the 'same content - multiple sidebar entries' case, the sidebar related frontmatter could be updates to optionally support a list of items.

[jeremyw24]

@mghill can I have an update on this issue, please close if no longer relevant.

[mghill]

I think this should be assigned to @kimburgess (though I cannot change it), and I believe in chats we determined that the slug-like solution is probably the best way forward. Also not critical to MVP, but probably one of the first non-top-critical enhancements IMO

[kimburgess]

Closing this with our current sidebar autogeneration in place. This mirrors the directory structure, and provide frontmatter support controlling order and labelling as detailed here.

There is active discussion in the upstream (facebook/docusaurus#3464), including a recent bump from their core team to confirm this is a priority feature. When that's out we can reopen this if it's not fit for our needs, but does not make sense to duplicate effort based on current information.

[mghill]

This was specifically in extension to the current autogeneration. Given the resolution to have the URL and Folder Structure closely tied and simple, I thought we resolved to have the sidebar more complexly controlled so that we can enrich it with more subfolders etc (without having them in the URL & therefore folder structure).

From a quick look the Docusaurus issue is only looking at formalising the autogeneration from folder structure (plus their version of the sidebar_label and sidebar_order system). Not sure if I missed something in that which would let you determine a sidebar category structure from the frontmatter of the docs themselves (only from sidebar.js or the file structure)

[kimburgess]

Ah yes, that's a little clearer. To confirm, the intent would be to have a directory (and URL) structure similar to:

- foo/
  - a.md
  - b.md
  - c.md
- bar/
  - e.md
  - f.md

But then present in nav as something like

- Category
  - Sub Category
    - a.md
    - c.md
  - b.md
  - e.md
  - Arbitrary
    - Nesting
      - f.md
      - a.md (again)

That is definitely technically achievable and I think the concept of a sidebar_path frontmatter that declares these positions sounds pretty neat.

If that's the case, can I get you to detail this with your ideal set of functionality in the original issue body. I'd still recommend that we hold on building this ourselves for as long as tolerable (in the space of weeks) so that we can see what falls out of Docusaurus' native support. If that's underwhelming, we'll at have a spec to jump straight onto implementing.

[mghill]

Yep, every part of that is exactly as it was in my head. I'll clarify a bit more in the top post

[slorber]

Hi there.

As I'm going to start working on the Docusaurus feature, I was wondering what's your use-case, if it could apply to many and if I should consider it for this feature?

Why do you want a different FS / Sidebar structure?

[kimburgess]

@slorber thanks for considering this in your research!

Within a docs site there are two main interfaces to the content:

1. URL
2. sidebar

In an ideal world, URL's should be immutable. Something that can be indexed, bookmarked, sent in mediums that cannot be updated (email, baked into a commit message etc). Keeping these succinct can also be a desirable feature - e.g. if following the documentation system /how-to/do-the-thing. They are a canonical reference to a piece of information.

Sidebars should then aid in discovery - associating related content, grouping concepts (including in potentially deeper hierarchies). Importantly as resources grow and change, this structure may also change to best represent the content. The structure is even more important with the DocPagination in Docusaurus as it gives readers a path they can follow when exploring unfamiliar ground.

In some cases this separation may not be required, but providing the ability to create this split would be a useful feature.

[slorber]

Thanks,

The URL of a doc is not tightly coupled to the FS structure, as you can specify a slug: /my/custom/path to any doc and ensure deep linking does not break.

And the sidebars.js allows you to create a sidebar hierarchy that is also decoupled from the file-system structure.

What I understand is that maybe you'd like a sidebar_breadcrumb: "Category 1 / Category 2" or something similar directly in the doc, but imho this is a bit complicated and wouldn't give you very good control over the order of docs/categories in the sidebar.

Can you give me a concrete example to achieve your goal using your ideal API surface, including file-structure, frontmatter, and the expected generated sidebar?

Eventually, we could provide a hook to implement your own sidebars generation logic.

// do whatever you want here, using all available doc metadatas (filename, dir, frontmatter...)
function myCustomGenerationFunction({ docs, version }) {
  // note: creating a tree in the correct order is not so simple
  // here it's a very simple impl using no categories at all
  return docs.map(d => ({
    type: "doc",
    label: doc.frontmatter?.sidebar_label || doc.title
  }));
}

module.exports = {
  defaultSidebar: [
    {
      type: "autogenerated", // New type implemented in https://github.com/facebook/docusaurus/pull/4582
      dirPath: ".", // Source of the dir to generate sidebar items from
      generate: myCustomGenerationFunction
    }
  ]
};

[kimburgess]

@slorber I missed the above - apologies for the lack of response.

The callback approach looks nice for any non-standard use cases. Super clean.

I noticed that alpha.73 is out with some of the functionality you've been working on. We'll give it a spin, then if there's any issues or features that warrant discussion can shift that over to the Docusaurus repo. Thanks again for taking the time to research needs ahead of building!

[slorber]

thanks, let me know if this works for you

There's already a callback on the docs plugin config that you can use, I think it's good enough and we may not need to add this to sidebars.js too, but let me know if this does not work for your usecase.