feat(v2): auto-generated sidebars, frontmatter-less sites (#4582)

* POC of autogenerated sidebars

* use combine-promises utility lib

* autogenerated sidebar poc working

* Revert "autogenerated sidebar poc working"

This reverts commit c81da980

* POC of auto-generated sidebars for community docs

* update tests

* add initial test suite for autogenerated sidebars + fix some edge cases

* Improve autogen sidebars: strip more number prefixes in folder breadcrumb + slugs

* fix typo!

* Add tests for partially generated sidebars + fix edge cases + extract sidebar generation code

* Ability to read category metadatas file from a file in the category

* fix tests

* change position of API

* ability to extract number prefix

* stable system to enable position frontmatter

* fix tests for autogen sidebar position

* renamings

* restore community sidebars

* rename frontmatter position -> sidebar_position

* make sidebarItemsGenerator fn configurable

* minor changes

* rename dirPath => dirName

* Make the init template use autogenerated sidebars

* fix options

* fix docusaurus site: remove test docs

* add _category_ file to docs pathsToWatch

* add _category_ file to docs pathsToWatch

* tutorial: use sidebar_position instead of file number prefixes

* Adapt Docusaurus tutorial for autogenerated sidebars

* remove slug: /

* polish the homepage template

* rename _category_ sidebar_position to just "position"

* test for custom sidebarItemsGenerator fn

* fix category metadata + add link to report tutorial issues

* fix absolute path breaking tests

* fix absolute path breaking tests

* Add test for floating number sidebar_position

* add sidebarItemsGenerator unit tests

* add processSidebars unit tests

* Fix init template broken links

* windows test

* increase code translations test timeout

* cleanup mockCategoryMetadataFiles after windows test fixed

* update init template positions

* fix windows tests

* fix comment

* Add autogenerated sidebar items documentation + rewrite the full sidebars page doc

* add useful comment

* fix code block title

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

@@ -30,6 +30,7 @@ import getSlug from './slug';
 import {CURRENT_VERSION_NAME} from './constants';
 import globby from 'globby';
 import {getDocsDirPaths} from './versions';
+import {extractNumberPrefix, stripPathNumberPrefixes} from './numberPrefix';
 import {assertDocFrontMatter} from './docFrontMatter';
 
 type LastUpdateOptions = Pick<
@@ -121,37 +122,66 @@ export function processDocMetadata({
   });
   assertDocFrontMatter(frontMatter);
 
-  // ex: api/myDoc -> api
-  // ex: myDoc -> .
-  const docsFileDirName = path.dirname(source);
-
   const {
     sidebar_label: sidebarLabel,
     custom_edit_url: customEditURL,
+
+    // Strip number prefixes by default (01-MyFolder/01-MyDoc.md => MyFolder/MyDoc) by default,
+    // but ability to disable this behavior with frontmatterr
+    strip_number_prefixes: stripNumberPrefixes = true,
   } = frontMatter;
 
-  const baseID: string =
-    frontMatter.id || path.basename(source, path.extname(source));
+  // ex: api/plugins/myDoc -> myDoc
+  // ex: myDoc -> myDoc
+  const sourceFileNameWithoutExtension = path.basename(
+    source,
+    path.extname(source),
+  );
+
+  // ex: api/plugins/myDoc -> api/plugins
+  // ex: myDoc -> .
+  const sourceDirName = path.dirname(source);
+
+  const {filename: unprefixedFileName, numberPrefix} = stripNumberPrefixes
+    ? extractNumberPrefix(sourceFileNameWithoutExtension)
+    : {filename: sourceFileNameWithoutExtension, numberPrefix: undefined};
+
+  const baseID: string = frontMatter.id ?? unprefixedFileName;
   if (baseID.includes('/')) {
     throw new Error(`Document id [${baseID}] cannot include "/".`);
   }
 
+  // For autogenerated sidebars, sidebar position can come from filename number prefix or frontmatter
+  const sidebarPosition: number | undefined =
+    frontMatter.sidebar_position ?? numberPrefix;
+
   // TODO legacy retrocompatibility
   // The same doc in 2 distinct version could keep the same id,
   // we just need to namespace the data by version
-  const versionIdPart =
+  const versionIdPrefix =
     versionMetadata.versionName === CURRENT_VERSION_NAME
-      ? ''
-      : `version-${versionMetadata.versionName}/`;
+      ? undefined
+      : `version-${versionMetadata.versionName}`;
 
   // TODO legacy retrocompatibility
-  // I think it's bad to affect the frontmatter id with the dirname
-  const dirNameIdPart = docsFileDirName === '.' ? '' : `${docsFileDirName}/`;
+  // I think it's bad to affect the frontmatter id with the dirname?
+  function computeDirNameIdPrefix() {
+    if (sourceDirName === '.') {
+      return undefined;
+    }
+    // Eventually remove the number prefixes from intermediate directories
+    return stripNumberPrefixes
+      ? stripPathNumberPrefixes(sourceDirName)
+      : sourceDirName;
+  }
 
-  // TODO legacy composite id, requires a breaking change to modify this
-  const id = `${versionIdPart}${dirNameIdPart}${baseID}`;
+  const unversionedId = [computeDirNameIdPrefix(), baseID]
+    .filter(Boolean)
+    .join('/');
 
-  const unversionedId = `${dirNameIdPart}${baseID}`;
+  // TODO is versioning the id very useful in practice?
+  // legacy versioned id, requires a breaking change to modify this
+  const id = [versionIdPrefix, unversionedId].filter(Boolean).join('/');
 
   // TODO remove soon, deprecated homePageId
   const isDocsHomePage = unversionedId === (homePageId ?? '_index');
@@ -165,8 +195,9 @@ export function processDocMetadata({
     ? '/'
     : getSlug({
         baseID,
-        dirName: docsFileDirName,
+        dirName: sourceDirName,
         frontmatterSlug: frontMatter.slug,
+        stripDirNumberPrefixes: stripNumberPrefixes,
       });
 
   // Default title is the id.
@@ -212,6 +243,7 @@ export function processDocMetadata({
     title,
     description,
     source: aliasedSitePath(filePath, siteDir),
+    sourceDirName,
     slug: docSlug,
     permalink,
     editUrl: customEditURL !== undefined ? customEditURL : getDocEditUrl(),
@@ -224,6 +256,7 @@ export function processDocMetadata({
         )
       : undefined,
     sidebar_label: sidebarLabel,
+    sidebarPosition,
     frontMatter,
   };
 }