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

* make number prefix parsing logic configurable

* Make numberPrefixParser configurable + rename frontmatter + avoid parsing date/version patterns by default

* add more tests

* more test cases

packages/docusaurus-plugin-content-docs/src/numberPrefix.ts

@@ -5,23 +5,34 @@
  * LICENSE file in the root directory of this source tree.
  */
 
+import {NumberPrefixParser} from './types';
+
+// Best-effort to avoid parsing some patterns as number prefix
+const IgnoredPrefixPatterns = (function () {
+  // ignore common date-like patterns: https://github.com/facebook/docusaurus/issues/4640
+  const DateLikePrefixRegex = /^((\d{2}|\d{4})[-_.]\d{2}([-_.](\d{2}|\d{4}))?)(.*)$/;
+
+  // ignore common versioning patterns: https://github.com/facebook/docusaurus/issues/4653
+  // note: we could try to parse float numbers in filenames but that is probably not worth it
+  // as a version such as "8.0" can be interpreted as both a version and a float
+  // User can configure his own NumberPrefixParser if he wants 8.0 to be interpreted as a float
+  const VersionLikePrefixRegex = /^(\d+[-_.]\d+)(.*)$/;
+
+  return new RegExp(
+    `${DateLikePrefixRegex.source}|${VersionLikePrefixRegex.source}`,
+  );
+})();
+
 const NumberPrefixRegex = /^(?<numberPrefix>\d+)(?<separator>\s*[-_.]+\s*)(?<suffix>.*)$/;
 
-// 0-myDoc => myDoc
-export function stripNumberPrefix(str: string) {
-  return NumberPrefixRegex.exec(str)?.groups?.suffix ?? str;
-}
-
-// 0-myFolder/0-mySubfolder/0-myDoc => myFolder/mySubfolder/myDoc
-export function stripPathNumberPrefixes(path: string) {
-  return path.split('/').map(stripNumberPrefix).join('/');
-}
-
 // 0-myDoc => {filename: myDoc, numberPrefix: 0}
 // 003 - myDoc => {filename: myDoc, numberPrefix: 3}
-export function extractNumberPrefix(
+export const DefaultNumberPrefixParser: NumberPrefixParser = (
   filename: string,
-): {filename: string; numberPrefix?: number} {
+) => {
+  if (IgnoredPrefixPatterns.exec(filename)) {
+    return {filename, numberPrefix: undefined};
+  }
   const match = NumberPrefixRegex.exec(filename);
   const cleanFileName = match?.groups?.suffix ?? filename;
   const numberPrefixString = match?.groups?.numberPrefix;
@@ -32,4 +43,27 @@ export function extractNumberPrefix(
     filename: cleanFileName,
     numberPrefix,
   };
+};
+
+export const DisabledNumberPrefixParser: NumberPrefixParser = (
+  filename: string,
+) => ({filename, numberPrefix: undefined});
+
+// 0-myDoc => myDoc
+export function stripNumberPrefix(
+  str: string,
+  parser: NumberPrefixParser,
+): string {
+  return parser(str).filename;
+}
+
+// 0-myFolder/0-mySubfolder/0-myDoc => myFolder/mySubfolder/myDoc
+export function stripPathNumberPrefixes(
+  path: string,
+  parser: NumberPrefixParser,
+): string {
+  return path
+    .split('/')
+    .map((segment) => stripNumberPrefix(segment, parser))
+    .join('/');
 }