stable system to enable position frontmatter

packages/docusaurus-plugin-content-docs/src/__tests__/__fixtures__/site-with-autogenerated-sidebar/docs/Guides/02-guide2.md

@@ -0,0 +1,5 @@
+---
+id: guide2
+---
+
+Guide 2

packages/docusaurus-plugin-content-docs/src/__tests__/__fixtures__/site-with-autogenerated-sidebar/docs/Guides/_category_.json

@@ -0,0 +1,3 @@
+{
+  "position": 2
+}

packages/docusaurus-plugin-content-docs/src/__tests__/__fixtures__/site-with-autogenerated-sidebar/docs/Guides/a-guide-4.md

@@ -0,0 +1,5 @@
+---
+id: guide4
+---
+
+Guide 4

packages/docusaurus-plugin-content-docs/src/__tests__/__fixtures__/site-with-autogenerated-sidebar/docs/Guides/b-guide-5.md

@@ -0,0 +1,5 @@
+---
+id: guide5
+---
+
+Guide 5

packages/docusaurus-plugin-content-docs/src/__tests__/__fixtures__/site-with-autogenerated-sidebar/docs/Guides/guide-3.md

@@ -0,0 +1,6 @@
+---
+id: guide3
+position: 3
+---
+
+Guide 3

packages/docusaurus-plugin-content-docs/src/__tests__/__fixtures__/site-with-autogenerated-sidebar/docs/Guides/z-guide1.md

@@ -0,0 +1,6 @@
+---
+id: guide1
+position: 1
+---
+
+Guide 1

packages/docusaurus-plugin-content-docs/src/__tests__/index.test.ts

@@ -751,7 +751,7 @@ describe('site with doc label', () => {
   });
 });
 
-describe('site with full autogenerated sidebar', () => {
+describe.only('site with full autogenerated sidebar', () => {
   async function loadSite() {
     const siteDir = path.join(
       __dirname,
@@ -771,64 +771,92 @@ describe('site with full autogenerated sidebar', () => {
     return {content, siteDir};
   }
 
-  test('sidebar is fully autogenerated', async () => {
+  test.only('sidebar is fully autogenerated', async () => {
     const {content} = await loadSite();
     const version = content.loadedVersions[0];
 
     expect(version.sidebars).toEqual({
       defaultSidebar: [
         {
-          id: 'getting-started',
           type: 'doc',
+          id: 'getting-started',
         },
         {
-          id: 'installation',
           type: 'doc',
+          id: 'installation',
         },
         {
+          type: 'category',
+          label: 'Guides',
+          collapsed: true,
+          items: [
+            {
+              type: 'doc',
+              id: 'Guides/guide1',
+            },
+            {
+              type: 'doc',
+              id: 'Guides/guide2',
+            },
+            {
+              type: 'doc',
+              id: 'Guides/guide3',
+            },
+            {
+              type: 'doc',
+              id: 'Guides/guide4',
+            },
+            {
+              type: 'doc',
+              id: 'Guides/guide5',
+            },
+          ],
+        },
+        {
+          type: 'category',
+          label: 'API (label from _category_.json)',
           collapsed: true,
           items: [
             {
-              id: 'API/api-overview',
               type: 'doc',
+              id: 'API/api-overview',
             },
             {
+              type: 'category',
+              label: 'Core APIs',
               collapsed: true,
               items: [
                 {
-                  id: 'API/Core APIs/Client API',
                   type: 'doc',
+
+                  id: 'API/Core APIs/Client API',
                 },
                 {
-                  id: 'API/Core APIs/Server API',
                   type: 'doc',
+                  id: 'API/Core APIs/Server API',
                 },
               ],
-              label: 'Core APIs',
-              type: 'category',
             },
             {
+              type: 'category',
+              label: 'Extension APIs (label from _category_.yml)',
               collapsed: true,
               items: [
                 {
-                  id: 'API/Extension APIs/Plugin API',
                   type: 'doc',
+                  id: 'API/Extension APIs/Plugin API',
                 },
                 {
-                  id: 'API/Extension APIs/Theme API',
                   type: 'doc',
+                  id: 'API/Extension APIs/Theme API',
                 },
               ],
-              label: 'Extension APIs (label from _category_.yml)',
-              type: 'category',
             },
             {
-              id: 'API/api-end',
               type: 'doc',
+              id: 'API/api-end',
             },
           ],
-          label: 'API (label from _category_.json)',
-          type: 'category',
         },
       ],
     });

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

@@ -69,6 +69,10 @@ describe('stripPathNumberPrefix', () => {
 
 describe('extractNumberPrefix', () => {
   test('should extract number prefix if present', () => {
+    expect(extractNumberPrefix('0-My Doc')).toEqual({
+      filename: 'My Doc',
+      numberPrefix: 0,
+    });
     expect(extractNumberPrefix('1-My Doc')).toEqual({
       filename: 'My Doc',
       numberPrefix: 1,

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

@@ -14,6 +14,7 @@ type DocFrontMatter = {
   description?: string;
   slug?: string;
   sidebar_label?: string;
+  position?: number;
   custom_edit_url?: string;
   strip_number_prefixes: boolean;
 };
@@ -24,6 +25,7 @@ const DocFrontMatterSchema = Joi.object<DocFrontMatter>({
   description: Joi.string(),
   slug: Joi.string(),
   sidebar_label: Joi.string(),
+  position: Joi.number(),
   custom_edit_url: Joi.string().allow(null),
   strip_number_prefixes: Joi.boolean(),
 }).unknown();

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

@@ -30,7 +30,7 @@ import getSlug from './slug';
 import {CURRENT_VERSION_NAME} from './constants';
 import globby from 'globby';
 import {getDocsDirPaths} from './versions';
-import {stripNumberPrefix, stripPathNumberPrefixes} from './numberPrefix';
+import {extractNumberPrefix, stripPathNumberPrefixes} from './numberPrefix';
 import {assertDocFrontMatter} from './docFrontMatter';
 
 type LastUpdateOptions = Pick<
@@ -142,15 +142,19 @@ export function processDocMetadata({
   // ex: myDoc -> .
   const sourceDirName = path.dirname(source);
 
-  const baseID: string =
-    frontMatter.id ||
-    (stripNumberPrefixes
-      ? stripNumberPrefix(sourceFileNameWithoutExtension)
-      : sourceFileNameWithoutExtension);
+  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.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
@@ -252,6 +256,7 @@ export function processDocMetadata({
         )
       : undefined,
     sidebar_label: sidebarLabel,
+    position: sidebarPosition,
     frontMatter,
   };
 }

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

@@ -12,10 +12,10 @@ import {
   DocMetadataBase,
   SidebarItemsGenerator,
 } from './types';
-import {sortBy, take, last} from 'lodash';
+import {sortBy, take, last, orderBy} from 'lodash';
 import {addTrailingSlash} from '@docusaurus/utils';
 import {Joi} from '@docusaurus/utils-validation';
-import {stripNumberPrefix} from './numberPrefix';
+import {extractNumberPrefix} from './numberPrefix';
 import chalk from 'chalk';
 import path from 'path';
 import fs from 'fs-extra';
@@ -28,6 +28,9 @@ type CategoryMetadatasFile = {
   position?: number; // TODO handle it! sort category items
 };
 
+type WithPosition = {position?: number};
+type SidebarItemWithPosition = SidebarItem & WithPosition;
+
 const CategoryMetadatasFileSchema = Joi.object<CategoryMetadatasFile>({
   label: Joi.string().optional(),
   position: Joi.number().optional(),
@@ -86,7 +89,7 @@ function parseBreadcrumb(
 
 // TODO allow to customize this logic (docs cfg+sidebar.js)
 // TODO define and document proper API surface
-export const DefaultSidebarItemsGenerator: SidebarItemsGenerator = ({
+export const DefaultSidebarItemsGenerator: SidebarItemsGenerator = async ({
   item,
   docs: allDocs,
   version,
@@ -168,23 +171,26 @@ export const DefaultSidebarItemsGenerator: SidebarItemsGenerator = ({
   );
    */
 
-  function createDocSidebarItem(doc: DocMetadataBase): SidebarItemDoc {
+  function createDocSidebarItem(
+    doc: DocMetadataBase,
+  ): SidebarItemDoc & WithPosition {
     return {
       type: 'doc',
       id: doc.id,
       ...(doc.frontMatter.sidebar_label && {
         label: doc.frontMatter.sidebar_label,
       }),
+      ...(typeof doc.position !== 'undefined' && {
+        position: doc.position,
+      }),
     };
   }
 
   async function createCategorySidebarItem({
     breadcrumb,
   }: {
     breadcrumb: string[];
-  }): Promise<SidebarItemCategory> {
-    // TODO read metadata file from the directory for additional config?
-
+  }): Promise<SidebarItemCategory & WithPosition> {
     const categoryDirPath = path.join(
       version.contentPath,
       breadcrumb.join(BreadcrumbSeparator),
@@ -194,16 +200,23 @@ export const DefaultSidebarItemsGenerator: SidebarItemsGenerator = ({
 
     const {tail} = parseBreadcrumb(breadcrumb);
 
+    const {filename, numberPrefix} = extractNumberPrefix(tail);
+
+    const position = categoryMetadatas?.position ?? numberPrefix;
+
     return {
       type: 'category',
-      label: categoryMetadatas?.label ?? stripNumberPrefix(tail),
+      label: categoryMetadatas?.label ?? filename,
       items: [],
       collapsed: true, // TODO use default value
+      ...(typeof position !== 'undefined' && {position}),
     };
   }
 
   // Not sure how to simplify this algorithm :/
-  async function autogenerateSidebarItems(): Promise<SidebarItem[]> {
+  async function autogenerateSidebarItems(): Promise<
+    SidebarItemWithPosition[]
+  > {
     const sidebarItems: SidebarItem[] = []; // mutable result
 
     const categoriesByBreadcrumb: Record<string, SidebarItemCategory> = {}; // mutable cache of categories already created
@@ -270,5 +283,38 @@ export const DefaultSidebarItemsGenerator: SidebarItemsGenerator = ({
     return sidebarItems;
   }
 
-  return autogenerateSidebarItems();
+  const sidebarItems = await autogenerateSidebarItems();
+
+  /*
+  console.log({
+    unsorted: sidebarItems,
+    sorted: sortSidebarItems(sidebarItems),
+  });
+
+   */
+
+  return sortSidebarItems(sidebarItems);
 };
+
+// Recursively sort the categories/docs + remove the "position" attribute from final output
+function sortSidebarItems(
+  sidebarItems: SidebarItemWithPosition[],
+): SidebarItem[] {
+  const processedSidebarItems = sidebarItems.map((item) => {
+    if (item.type === 'category') {
+      return {
+        ...item,
+        items: sortSidebarItems(item.items),
+      };
+    }
+    return item;
+  });
+
+  const sortedSidebarItems = orderBy(
+    processedSidebarItems,
+    (item) => item.position,
+    ['asc'],
+  );
+
+  return sortedSidebarItems.map(({position: _removed, ...item}) => item);
+}

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

@@ -173,6 +173,7 @@ export type DocMetadataBase = LastUpdateData & {
   permalink: string;
   // eslint-disable-next-line camelcase
   sidebar_label?: string;
+  position?: number;
   editUrl?: string | null;
   frontMatter: FrontMatter;
 };