[v2.0.0-alpha.73] autogenerated sidebars: have a stripNumberPrefixes option in config file?

[valentine]

Hi,

I just upgraded my Docusaurus to alpha.73, and noticed #3464, #4582 and db79d46.

My site has its Markdown files named as yyyy-mm-dd.md, and alpha.73 tries to strip the number prefix for all the files.

Screenshot from when I try to start Docusaurus, because the prefixes got stripped out.

I'd like to propose that plugin-content-docs have a stripNumberPrefixes config option, so that I am able to disable this option for the entire plugin instance, without having to manually add the front matter to every Markdown file.

Alternatively, maybe some regex could be done to check if an ISO8601 date (e.g. yyyy-mm-dd or yyyymmdd) is the title or filename, and automagically disable the feature if so?

Also, it would be really cool if autogenerated sidebars could be generated in reverse alphabetical/chronological order (i.e. the newest is on top). Please let me know if I should start a separate issue for this!

Thanks!

Edit: thinking about it some more, I think prefixes should not be stripped if the user has explicitly created a non-autogenerated sidebar file. That seems like too much magic.

[slorber]

I'd like to propose that plugin-content-docs have a stripNumberPrefixes config option, so that I am able to disable this option for the entire plugin instance, without having to manually add the front matter to every Markdown file.

Agree we should have a global docs plugin option for this in addition to the existing frontmatter.

I'd like the config to allow you to pass a custom function parseNumberPrefix to parse file/folder names as position+rest the way you want, using false to disable this feature. Would it work for you?

Alternatively, maybe some regex could be done to check if an ISO8601 date (e.g. yyyy-mm-dd or yyyymmdd) is the title or filename, and automagically disable the feature if so?

Agree, as using dates in filenames is probably a common pattern.

Also, it would be really cool if autogenerated sidebars could be generated in reverse alphabetical/chronological order (i.e. the newest is on top). Please let me know if I should start a separate issue for this!

Agree.

You can write a custom sidebar items generators for this but it's not very convenient as it's not so easy to implement.
https://docusaurus.io/docs/sidebar#customize-the-sidebar-items-generator

We could allow that custom generation function to use the default docusaurus sitebar items generator, so that you can post-process it somehow.

module.exports = {
  plugins: [
    [
      '@docusaurus/plugin-content-docs',
      {
        sidebarItemsGenerator: async function ({defaultSidebarItemsGenerator,...rest}) {
          const sidebar = await defaultSidebarItemsGenerator(rest);
          return changeSidebarItemsOrder(sidebar);
        },
      },
    ],
  ],
};

It would be your responsibility to write the changeSidebarItemsOrder function.

It may not be the simplest API for this specific usecase but I think it's nice as it's flexible for many usecases and does not introduce a new API. Does it make sense?

Edit: thinking about it some more, I think prefixes should not be stripped if the user has explicitly created a non-autogenerated sidebar file. That seems like too much magic.

Unfortunately, it would be a bit complicated to do that, as Docusaurus reads the docs and strip prefixes even before handling anything related to the sidebars, so it would involve quite a complex refactoring that is probably not worth it. If this number prefix feature becomes annoying for a lot of users we could simply disable it by default.

[valentine]

I'd like the config to allow you to pass a custom function parseNumberPrefix to parse file/folder names as position+rest the way you want, using false to disable this feature. Would it work for you?

Yes, this would be great. It sounds like it'll at least revert back to the behaviour from alpha.72.

It would be your responsibility to write the changeSidebarItemsOrder function.

It may not be the simplest API for this specific usecase but I think it's nice as it's flexible for many usecases and does not introduce a new API. Does it make sense?

I think choosing between either the batteries-included or flexible API approach might depend on how many other users end up requesting to sort stuff by ascending/descending order. I think ascending/descending sort, at the very least, could be a reasonable complement to the new autogenerated sidebars feature.

If there are other fancy use cases that you might be able to think of, exposing it as a separate API might make sense then.

Personally, as someone looking to adopt Docusaurus, I'd like it if I could just drop in a couple of Markdown files, configure everything in docusaurus.config.js without having to write functions myself (or hunt around for code snippets), and get a docs site up and running in a few minutes.

[slorber]

Configurable parser and ignoring date patterns by default will be in #4655

For sorting the sidebars, for now I'll only document this use-case pattern in the docs plugin doc, and if this becomes requested quite often we'll try to design an API for this.

Designing this API may not be the easiest, there are multiple solutions to solve this use-case, and I'd like to avoid rushing on implementing something until I know better the use-case of other users.

[slorber]

Sidebar ordering will be solved with a low-level API for now, introduced in #4658

// Reverse the sidebar items ordering (including nested category items)
function reverseSidebarItems(items) {
  // Reverse items in categories
  const result = items.map(item => {
    if (item.type === "category") {
      return { ...item, items: reverseSidebarItems(item.items) };
    }
    return item;
  });
  // Reverse items at current level
  result.reverse();
  return result;
}

module.exports = {
  plugins: [
    [
      "@docusaurus/plugin-content-docs",
      {
        sidebarItemsGenerator: async function({
          defaultSidebarItemsGenerator,
          ...args
        }) {
          const sidebarItems = await defaultSidebarItemsGenerator(args);
          return reverseSidebarItems(sidebarItems);
        }
      }
    ]
  ]
};

This is now the most straightforward but is flexible. It is a good enough workaround until we see if there is traction for a proper sorting API, and gives time to design it. As autogen sidebar is now, we'll see if there is demand for such an API in the near future.