felipecrs commented 4 years ago

🚀 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 commented 4 years ago

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

slorber commented 4 years ago

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 notifications@github.com 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 commented 4 years ago

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 commented 4 years ago

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 commented 4 years ago

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 commented 4 years ago

@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 commented 4 years ago

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 commented 4 years ago

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 commented 4 years ago

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

Clindbergh commented 3 years ago

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 commented 3 years ago

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

slorber commented 3 years ago

Sure please do, thanks

Le jeu. 12 nov. 2020 à 21:15, vthirupathi notifications@github.com 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 commented 3 years ago

+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

polarathene commented 3 years ago

I was looking into this feature for a project that's migrating away from Github Wiki for their docs (links to detailed discussion comparing the merits between MkDocs and Docusaurus v2 for a community project with few maintainers, reliant on contributors and minimal web dev experience for most).

MkDocs by default generates the sidebar based on the docs folder and lists items in alphanumeric order. It also supports directories which are being sorted below files at the same level. If a user wants to control the navigation they add a hierarchy similar to sidebar.js in the mkdocs.yml under the nav property, where they can reference files and assign friendly label names (or leverage title in a files frontmatter).

I noticed that Docusaurus doesn't explicitly state sidebarPath as required in the docs and was curious what happens if I omit it. This just disables the sidebar completely instead of allowing an implicit fallback similar to MkDocs.

These additional gotchas and config overhead like this issue are making Docusaurus a less attractive option to adopt despite my advocating for the flexibility and powerful configuration that Docusaurus brings to the table. I think this is an important consideration to sort out for v2 while in alpha (especially since the docs state that sidebarPath isn't a reliably stable prop and is subject to change at present.

I did come across a third-party Docusaurus plugin (acrobit/docusaurus-plugin-auto-sidebars) that addresses this feature if anyone is interested, but I don't think it's a solid solution in it's present state.

Test run placed the directories near the bottom of the sidebar, but there was a regular file entry beneath this, possibly a sorting / insert bug that was off by 1.
It's {docs: 'mydocs'} folder feature, that's a bit vague doesn't appear to be usable. I've not inspected source but tried various attempts at getting different docs from this and nothing happened.
Custom hierarchy depends on a separate sidebars.yaml placed within the docs folder, this seems to be an implicit hard-coded reference. Being able to configure via YAML vs JS is considered a bonus over sidebar.js for some users (notably preferred by maintainers in project discussion I linked), but this approach is a bit ugly (1st element is a string for parent folder, subsequent elements are key/value mappings, but accept string label or false boolean to hide, worse when also considering parent folder sorting that the README describes at the bottom). This file also only covers folder hierarchy, they only support file sort order via explicit filename number prefix.

For the basic purpose of generating the sidebar implicitly, it's quite useful especially when you're migrating your docs over from another docs platform.

It'd be nice if you could additionally define a sidebar.js definition as present but with an item type that will source a directory (and thus all nested children) to auto-populate that content.
Sorting implicitly with alphanumeric filename or some frontmatter prop could also work nicely?

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.

@rudasn this is a nice idea :+1:

I think it's better to avoid regular docs files having anything specific to the category/directory docs are located in via their frontmatter especially when dependent on sort order.

The _category.md just providing frontmatter can be optional and explicitly allow customizing metadata for that directory's category name and sort priority, making it quite portable if docs need to be re-organized and moved around (which for the wiki I contribute to has happened a few times).

I don't think that categories or docs need individual sort priority properties. They just need to provide a number, and that can easily be collected into an array for content at that level using native sort ({category_id: '<path or hash>', sort_priority: 5}, just sort an array of objects via the sort_priority key and you'll have the order and a related key to identify that category uniquely).

@slorber

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.

They should not require that, the feature afaik is primarily for convenience and would additionally help with new user adoption especially for projects migrating and wanting to get a minimal setup going with their existing docs (possibly already structured via folder hierarchy).

There should be minimal friction towards this. Being more explicit or having other features when required, especially if available piecemeal (eg sidebar.js config that allows some nested content to remain auto-generated).

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.

These are all great features and I think they speak greatly for the capabilities of Docusaurus. As a new user evaluating Docusaurus, the default "hello world" project that the docs introduce was a nice overview with the landing page and complimentary blog and footer links.

I didn't need any of that though and had to figure out what I could strip out. I used the "docs only" mode which required some additional configuration changes along with some build errors from the boilerplate which had me sifting through the docs to grok how to produce a focused demo of what Docusaurus can do for docs specifically.

We have no external links. I don't know what refs are (markdown frontmatter id that from what I could gather from the docs can't be used to as links to other docs within markdown files?); The docs suggest that I can't use filepaths and need to add frontmatter to add id values for each doc to reference in sidebar.js? (EDIT: Frontmatter id doesn't appear to be required, but the docs for sidebar items implies it, or doesn't communicate the distinction well, the Document ID link is invalid but the correct page for that properly explains it. I believe I was following some old Github Wiki migration to Docusaurus advice that stated the frontmatter was required)

Setting up the sidebar.js required investing quite a bit more time by the friction it added to put together a Docusaurus demo with existing docs, with minimal benefit vs copy/pasting the flat Github Wiki structure to nested folders and not being too concerned about the sort order until a decision to adopt a new documentation solution was made. I wasn't aware of the autogeneration plugin I linked at the time unfortunately.

I read about multiple sidebars, but don't recall that in the getting started demo, and not sure if that clicked very well when I saw it in the docs. I'm sure it has it's uses, but for someone like me who wanted to just autogenerate docs to get started and play around with real docs, none of these extra features were immediately important and I'm sure would be more acceptable when actually required.

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

Again not something I used. Seemed like a nice feature, but the docs did warn caution against it due to the way versioning is implemented. vector.dev is a good customized Docusaurus deployment, but in early 2020 they expressed dissatisfaction with Docusaurus v2 versioning approach, their code maintains prior versions via branches for point release updates and they need the code to match the version.

Thus they can't make updates to old code on the master branch and for them there isn't value in having a group of directories named by version release since they'd fall out of sync with the codebase and serve little value for them while confusing contributors (or users viewing older docs since the edit page links to master instead of the versioned branch). At least that's what I gathered from that link.

From what I can tell, they seem to be migrating to Gatsby instead, I'm not sure if it's due to that issue or other reasons. For the project I'm contributing to, the versioning feature sounds desirable, but we also want to keep the docs folder simple for contributors, the versioned branch approach that vector takes (or using tags) seems more ideal.

TL;DR

From perspective of someone evaluating between MkDocs and Docusaurus v2 for migrating a reasonably popular open-source project from Github Wiki docs, Docusaurus is brilliant but has some pain points in adoption vs MkDocs for the given project demographic/maintainership.
acrobit/docusaurus-plugin-auto-sidebars does a barebones job of the feature, but has issues, especially for how they approached additional configuration. I haven't tried other suggestions in this issue.
_category.md and frontmatter seems like an excellent approach for adjusting the sorting order and directory/category names.
sidebar.js being able to support a mixture of explicit and implicit (auto-generated sidebar content for sub-hierarchies) would be pretty great too.
All those extra features and concerns may be valid, but that doesn't mean they all need to be supported by this implicit sidebar approach. Some users especially new users evaluating Docusaurus against alternative solutions may very well not need complimentary features to begin with and just appreciate minimal friction
- Especially when they've got existing docs and getting a build of Docusaurus running with those docs running relying on just directory hierarchy and alphanumeric sorting to begin with can be more than enough vs requiring explicit sidebar.js.

Pl8tinium commented 3 years ago

hi i have nothing to do with all of this but here are my 2 cents.... i just wanted to enforce your last point @polarathene. im currently searching for an alternative for raneto and it bogs me that there is no auto generation for the sidebar. Its marked as a big point in my disadvantages list, bc of the manual additional steps i need to take.

polarathene commented 3 years ago

@Pl8tinium for the time being you can leverage the docusaurus plugin I mentioned or other solutions shared here prior.

If you'd like to consider MkDocs I can confirm it's easy to setup locally if opting for the more featured (by default) MkDocs Material theme (more like a preset in Docusaurus AFAIK?), which provides a Docker image for quick sandboxed build and serve. I noticed Docusaurus v1 has mention of Docker in it's docs, but this seems to be missing for v2, I found a third-party image as I wasn't too interested in setting up my own atm, but it was rather lacking.

Setting up the Github Actions workflow is also pretty easy for deployments on push to master/main branch. Docusaurus docs are a bit over-complicated for this, I recently picked up Github Actions for CI and have an easier workflow that I'll contribute to the docs for the benefit of others.

I have found MkDocs has a third-party plugin/extension called awesome-pages, I haven't set this up yet but AFAIK it's just a pip install as documented for adding to a Github Actions workflow run step, or if using the MkDocs Material Docker image, extending it via a Dockerfile with the relevant pip install command.

Then you just update the mkdocs.yml's nav property or add .pages file into your docs directories whenever you want to adjust default implicit generation behavior, such as assigning more friendly label name to a directory or setting the sort order explicitly for that directories children, where you can position ... anywhere in the list order and it'll spread/expand the remaining items while respecting your explicit config items.

This is quite a nice workflow for tackling the solution and might be a useful reference for Docusaurus to consider? Something like awesome-pages would probably be adequate for most users needs here?

There's a related feature request for upstream MkDocs (since 2015) as MkDocs only offers explicit or implicit sidebar/nav without that linked extension. In that feature request, the OP is referencing GlusterFS docs which involved a 200 line config for nav where sometimes it'd be nice to just explicitly declare top-level categories and then glob the directory files and any nested children.

Pl8tinium commented 3 years ago

@Pl8tinium for the time being you can leverage the docusaurus plugin I mentioned or other solutions shared here prior.

thanks for that suggestion.

i should have said ... "that there is no integrated auto generation"

still probably going to pick docusaurus bc of the customizability

shinebayar-g commented 3 years ago

This is much needed feature. We have tons of markdown files divided into subfolders. It would be brilliant if Docusaurus supported targeting subdirectories instead of 1:1 matching everything. It's indeed error prone, we just noticed couple of docs weren't actually mapped to the sidebar because of developers didn't update the sidebars.js file.

slorber commented 3 years ago

FYI, we have decided that this feature is a top priority for the beta launch, and I'll work on this very soon!

Will read again all your comments before I start.

It is a very visible feature that can make Docusaurus more intuitive for newcomers: some end up creating a doc file and don't really understand how to navigate to this doc file, as it requires reading the doc to know about the sidebars.js file.

In general, I believe we should make it easier to use Docusaurus without any frontmatter at all for the most simple cases.

We'll move the init template example to have no sidebars.js file, and also dogfood this on our own website.

Just merged this PR that allows using a markdown heading like # Title instead of frontmatter title: "Title".

I also think we should support ordering with a numbered prefix as it's a quite popular convention. The filename can become the doc title (with the prefix number stripped)

The new init template might look like:

docs
├ 1-Intro.md
├ 2-Getting Started.md
├ 3-Tutorial.md
└-4-Advanced guides.md

We'll also support auto-generating only a "slice" of your sidebar, so that you can have more control over some other parts and yet keep the reduced boilerplate of auto-generation (and we'll dogfood that on the Docusaurrus site itself as we want to display the new init template docs tutorial here!)

Does this all make sense?

arinthros commented 3 years ago

@slorber I love the 'slice' concept. We follow this general sidebar structure when using Docusaurus v2.

- Getting Started // .md or .mdx
- Contributing // .md or .mdx
- API Reference // folder, everything inside of here is auto-generated and my `docs:generate` script recursively scans this folder and updates sidebars.js based on nested folder and file structure
  - helpers // folder
    - someFunction // .md or .mdx file

vjpr commented 3 years ago

Great to see this taking priority!

slices

This is the right approach.

I would stress that it would be great to have a hook function that allows full customization of the sidebar allowing anyone to override the default implementation (that function would take arguments of all id file mappings as I mentioned elsewhere).

I also think we should support ordering with a numbered prefix as it's a quite popular convention.

Re-ordering can be difficult. Prisma use a cli tool though -> https://github.com/prisma/docs#inserting-moving-and-deleting-files. Maybe good to mention somewhere in docs...or even support it via a docusaurus cli.

slorber commented 3 years ago

Asking for feedbacks

I've made some progress on this feature and would like to have your feedbacks.

Sidebar configuration:

You can use a new sidebar item type autogenerated, and it will generate a sidebar slice :

module.exports = {
  mySidebar: [
    'my-doc-1'
    {
      type: 'category',
      label: 'Some category',
      items: [
        'my-doc-2'
        {
          type: 'autogenerated',
          dirName: 'api', // generate sidebar slice from docs/api (or versioned_docs/version/api)
        },
      ],
    },
  ],
};

By default, a Docusaurus site will auto-generate from its website/docs folder.

The default/fallback sidebar config in case sidebars.js is absent:

module.exports = {
  defaultSidebar: [
    {
      type: "autogenerated",
      dirName: "." // generate sidebar slice from docs (or versioned_docs/version)
    }
  ]
};

A "sidebar slice" will generate a list of sidebar items (be replaced with), and you can "concat" 2 sidebar slices under a single sidebar category if you want:

module.exports = {
  mySidebar: [
    {
      type: "category",
      label: "Guides",
      items: [
        {
          type: "autogenerated",
          dirName: "guides/tutorial"
        },
        {
          type: "autogenerated",
          dirName: "guides/i18n"
        }
      ]
    }
  ]
};

Category metadata file

Docusaurus will look for a _category_.json or _category_.yml file in autogenerated dirs, on which you will be able to provide sidebar category item attributes like collapsible, label

When we'll implement category index files, we'll read this metadata directly on the Category/index.md frontmatter too.

Sidebar ordering

A new category and doc metadata/frontmatter sidebar_position will be used in priority

By default, Docusaurus will look for number prefix patterns in filenames and dirnames, and try to use those when there is no explicit sidebar_position

The number prefixes will be stripped to keep clean slugs/urls, titles and ids, so that in most cases you don't need to provide custom frontmatter. You can opt-out from extracting the number prefix from filenames if your doc really needs to start with a number (strip_number_prefixes: false).

Provide your own generator

Docusaurus has a default way to generate a sidebar from the FS. We could allow users to provide their own generator function by using docs plugin like sidebarGenerator: ({item, version, docs}) => ([]).

It would be a hook/function that would receive the "autogenerated" sidebar items we found, and would have to return the sidebar slice that would replace the autogenerated item. It would receive the version and all available docs metadatas.

Signature

export type SidebarItemsGenerator = (generatorArgs: {
  item: SidebarItemAutogenerated;
  version: VersionMetadata;
  docs: DocMetadataBase[];
}) => Promise<SidebarItem[]>;

Feedback questions

About the new sidebar item autogenerated:

Is autogenerated a good name for this?

About position metadata:

Should we allow float numbers or limit to ints? Can float be useful to "interleave" a new doc anywhere between 2 existing docs?
What should be the name of the docs/category sidebar metadata/frontmatter used for ordering. Is sidebar_position appropriate?
Is the position used only to order inside the current sidebar slice, or it is used to order the category in general (ie if a category contains 2 sidebar slices, the items of the 2 sidebar slices could be interleaved?)
Should we allow to add a position metadata to docs/categories also in the regular sidebars.js docs and categories? (non auto-generated items).
My opinion is that the position metadata should only sort "inside a sidebar slice", or it could be confusing: you could position manually a doc in a sidebar, and have it unexpectedly repositioned differently after the sidebar has been sorted.

About number prefixes:

What are the most common patterns for prefixing dirs/filenames with numbers? Do you have doc links to share?

About sidebarGenerator custom generator function:

What is the minimal version/docs metadata we should provide? (we probably don't want to create a too large API surface here or it can be complicated to avoid breaking changes)
Should we allow any custom metadata on the autogenerated item, so that you could use it on the fn?
Should we inject all available docs of the version, or only a subset (ie filtered by a dir? which means the "dirPath" option is always required?)
Should we provide dir paths / docs paths relative to the version docs root website/docs or relative to the dirPath folder?

Worth mentioning:

We only generate categories for folders containing actual docs
Using number prefixes can be annoying for linking with relative md file paths, as changing the prefix means changing the markdown link

slorber commented 3 years ago

Let me know if anyone has any feedback or concern with my implementation, names or anything.

The PR is ready to merge, just need to add the doc now so will likely merge it tomorrow.

felipecrs commented 3 years ago

The proposed design seems very good to my perspective. I don't have any concerns.

arinthros commented 3 years ago

@slorber I read through this the other day, and had some time to process. Overall I think this is a great approach, well done. I don't think we would have a use case for numerical sort ordering of auto-generated content, we prefer the default alphabetical ordering of file names/titles so it's easier to find in the nav. But maybe there are others who would use numbering?

Is autogenerated a good name for this?

Sounds good to me. It's explicit about its purpose.

Is the position used only to order inside the current sidebar slice, or it is used to order the category in general (ie if a category contains 2 sidebar slices, the items of the 2 sidebar slices could be interleaved?)

I would think the numbering would be scoped to the slice, so not interleaved. I think the complexity of interleaving could be its own feature - or some sort of param boolean to enable or merge sort order. How would conflicts be handled?

Should we allow to add a position metadata to docs/categories also in the regular sidebars.js docs and categories? (non auto-generated items). My opinion is that the position metadata should only sort "inside a sidebar slice", or it could be confusing: you could position manually a doc in a sidebar, and have it unexpectedly repositioned differently after the sidebar has been sorted.

Agreed. Re-sorting a manually sorted list could lead to unintended confusion/bugs.

arinthros commented 3 years ago

If we want a custom sort order, we would manually do that in the sidebar.js file and use slices for the rest. So maybe slices would ignore plucked files, kind of how object spread works in React?

const { title, url, ...rest } = props

slorber commented 3 years ago

Thanks for the feedbacks, so it seems my implementation is good enough to merge.

@arinthros

If we want a custom sort order, we would manually do that in the sidebar.js file and use slices for the rest. So maybe slices would ignore plucked files, kind of how object spread works in React?

const { title, url, ...rest } = props

For now we don't "deduplicate" items, so basically you can do that and end-up with the sidebar slice being generated twice:

module.exports = {
  mySidebar: [
    {
      type: "autogenerated",
      dirName: "tutorials"
    },
    {
      type: "autogenerated",
      dirName: "tutorials"
    }
  ]
};

I don't think we shuld do anything clever regarding this kind of situation.

We could add a way to include/exclude some docs by using glob patterns:

module.exports = {
  mySidebar: [
    {
      type: "autogenerated",
      dirName: "tutorials"
      include: "**/easy-*.md"
    },
    {
      type: "autogenerated",
      dirName: "tutorials"
      include: "**/easy-*.md"
    }
  ]
};

I don't think this is needed now, but that can be added later if this is requested.

0Grit commented 2 years ago

@slorber is there a way to specify items within an autogenerated slice by file?

Possibly use the items key inside of a _category_.yml?

I want just the top level of my slice to be autogenerated to avoid confusion for others maintaining another section of our docs that want to use autogenerated slices all the way down.

Josh-Cena commented 2 years ago

@0Grit See #5689. This is another enhancement request.

slorber commented 2 years ago

yes #5689 is a good place to discuss that.

@0Grit I'd appreciate to understand better your use-case: why deeply nested auto-generation is confusing and why do you want to opt-out of it? Why do you want to keep subfolders in the autogenerated folder?

0Grit commented 2 years ago

@slorber I have a perception that git diffs will be cleaner and rebases will also have less merge conflicts if I'm encoding my documentation structure in a file versus using the file-system concept to set the doc structure.

0Grit commented 2 years ago

Documentation structure as code versus documentation structure as filesystem. It is easier to change the contents of a limited number of files versus moving files around the filesystem and having to modify lots of __category_.yml files.

0Grit commented 2 years ago

This is my personal preference having experiences with this sort of thing in the past. Other people on the team including maintainer of our docs repository currently prefer the autogeneration.

slorber commented 2 years ago

@0Grit it's still hard to understand to me.

If you just auto-generate on a single level, why don't you just not auto-generate and declare an explicit sidebar category instead? Subcategories can still be auto-generated if needed.

You can put all your docs flat in a single folder and create your sidebar tree manually: no file move needed

0Grit commented 2 years ago

@slorber Yes, your recommendation, is what I was going to end up doing. I didn't want to need to change sidebar.js to do it. I also thought it might be nice to be able to specify my sidebar in a more modular fashion with __category__.yml or some other file as desired.

facebook / docusaurus

Auto generate sidebar according to the docs folder structure #3464

🚀 Feature

Have you read the Contributing Guidelines on issues?

Motivation

Pitch

TL;DR

Asking for feedbacks

Sidebar configuration:

Category metadata file

Sidebar ordering

Provide your own generator

Feedback questions