feat(v2): docs, make numberPrefixParser configurable, better defaults, minor breaking-changes

[slorber]

Motivation

Alpha 73 introduced autogenerated sidebars with support for number prefixes like 01-My Folder/02-My Doc.

This default non-configurable logic is annoying for some users that use numbers in filenames that should rather not be interpreted as numbers prefixes by default:

• Date patterns like 2021-01: [v2.0.0-alpha.73] autogenerated sidebars: have a stripNumberPrefixes option in config file? #4640
• Versioning patterns like 8.0.0/MyDoc: [2.0.0-alpha.73] Numeric value in subdirectory of DOCS yields issues with sideba #4653

As it's impossible to predict all possible filename patterns that a Docusaurus would like to use, we try to provide good opinionated defaults and ignore some common patterns.

This new default behavior can be disabled entirely and revert back to a post-alpha-73 behavior, or the user can also provide its own parsing logic:

        numberPrefixParser: function (filename) {
          // Implement your own logic to extract a potential number prefix
          const numberPrefix = findNumberPrefix(filename);
          // Prefix found: return it with the cleaned filename
          if (numberPrefix) {
            return {
              numberPrefix,
              filename: filename.replace(prefix, ''),
            };
          }
          // No number prefix found
          return {numberPrefix: undefined, filename};
        },

Minor breaking changes (from alpha.73):

• rename doc frontmatter: strip_number_prefix to parse_number_prefix for consistency
• changes in the default numberPrefixParser (now ignore dates and versions)

Have you read the Contributing Guidelines on pull requests?

yes

Test Plan

tests

[netlify]

[V1]

Built with commit 57559ec

https://deploy-preview-4655--docusaurus-1.netlify.app

[netlify]

[V2]

Built with commit 57559ec

https://deploy-preview-4655--docusaurus-2.netlify.app

[github-actions]

⚡️ Lighthouse report for the changes in this PR:

Category	Score
🔴 Performance	40
🟢 Accessibility	96
🟢 Best practices	100
🟢 SEO	100
🟢 PWA	95

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

[netlify]

[V2]

Built with commit 1805a93

https://deploy-preview-4655--docusaurus-2.netlify.app

[github-actions]

Size Change: 0 B

Total Size: 630 kB

ℹ️ View Unchanged

Filename	Size	Change
website/build/assets/css/styles.********.css	87.5 kB	0 B
website/build/assets/js/main.********.js	453 kB	0 B
website/build/blog/2017/12/14/introducing-docusaurus/index.html	62.3 kB	0 B
website/build/docs/introduction/index.html	235 B	0 B
website/build/index.html	27.1 kB	0 B

_{compressed-size-action}

[netlify]

[V1]

Built with commit 1805a93

https://deploy-preview-4655--docusaurus-1.netlify.app

[valentine]

Not really sure where I should comment, but I would like to propose that yyyymmdd be ignored as well.

^\d{8}(.*)$ would match 20210422.md and more.

If we want to add slightly more complexity, ^[19|20]{2}\d{2}[0|1]{1}\d{1}[0-3]{1}\d{1}(.*)$ could help ensure that it is a (mostly) valid date.

[slorber]

@valentine we have the infra in place for customizations, and PRs are welcome.

I don't think we'll ever find the perfect opinionated regex to fit all usecases by default. Some users would be happy if 20210422-my-doc.md was converted to /MyDoc, and some would prefer to have /20210422-my-doc

Note that we don't extract number prefixes if there is no separator such as -_. so in your case 20210422.md will not be processed (otherwise it would have an empty suffix)

If you want these heuristics to keep being improved please open a proper bug report explaining how something is affecting you in practice. I think you didn't encounter any bug or annoyance yet right?

[valentine]

@slorber Thanks for your thoughts. Yes, this won't affect me, especially after alpha.74 is released.

I was preemptively thinking how it might be possible to make this feature better, but it looks like I completely looked past how a number without a separator won't be affected anyway.