@docusaurus/plugin-content-docs 0.0.0-4240 → 0.0.0-4244

package/src/__tests__/__snapshots__/translations.test.ts.snap

@@ -8,6 +8,14 @@ Array [
         "description": "The label for category Getting started in sidebar docs",
         "message": "Getting started",
       },
+      "sidebar.docs.category.Getting started.link.generated-index.description": Object {
+        "description": "The generated-index page description for category Getting started in sidebar docs",
+        "message": "Getting started index description",
+      },
+      "sidebar.docs.category.Getting started.link.generated-index.title": Object {
+        "description": "The generated-index page title for category Getting started in sidebar docs",
+        "message": "Getting started index title",
+      },
       "sidebar.docs.link.Link label": Object {
         "description": "The label for link Link label in sidebar docs, linking to https://facebook.com",
         "message": "Link label",
@@ -25,6 +33,14 @@ Array [
         "description": "The label for category Getting started in sidebar docs",
         "message": "Getting started",
       },
+      "sidebar.docs.category.Getting started.link.generated-index.description": Object {
+        "description": "The generated-index page description for category Getting started in sidebar docs",
+        "message": "Getting started index description",
+      },
+      "sidebar.docs.category.Getting started.link.generated-index.title": Object {
+        "description": "The generated-index page title for category Getting started in sidebar docs",
+        "message": "Getting started index title",
+      },
       "sidebar.docs.link.Link label": Object {
         "description": "The label for link Link label in sidebar docs, linking to https://facebook.com",
         "message": "Link label",
@@ -42,6 +58,14 @@ Array [
         "description": "The label for category Getting started in sidebar docs",
         "message": "Getting started",
       },
+      "sidebar.docs.category.Getting started.link.generated-index.description": Object {
+        "description": "The generated-index page description for category Getting started in sidebar docs",
+        "message": "Getting started index description",
+      },
+      "sidebar.docs.category.Getting started.link.generated-index.title": Object {
+        "description": "The generated-index page title for category Getting started in sidebar docs",
+        "message": "Getting started index title",
+      },
       "sidebar.docs.link.Link label": Object {
         "description": "The label for link Link label in sidebar docs, linking to https://facebook.com",
         "message": "Link label",
@@ -177,6 +201,13 @@ Object {
               },
             ],
             "label": "Getting started (translated)",
+            "link": Object {
+              "description": "Getting started index description (translated)",
+              "permalink": "/docs/category/getting-started-index-slug",
+              "slug": "/category/getting-started-index-slug",
+              "title": "Getting started index title (translated)",
+              "type": "generated-index",
+            },
             "type": "category",
           },
           Object {
@@ -317,6 +348,13 @@ Object {
               },
             ],
             "label": "Getting started (translated)",
+            "link": Object {
+              "description": "Getting started index description (translated)",
+              "permalink": "/docs/category/getting-started-index-slug",
+              "slug": "/category/getting-started-index-slug",
+              "title": "Getting started index title (translated)",
+              "type": "generated-index",
+            },
             "type": "category",
           },
           Object {
@@ -457,6 +495,13 @@ Object {
               },
             ],
             "label": "Getting started (translated)",
+            "link": Object {
+              "description": "Getting started index description (translated)",
+              "permalink": "/docs/category/getting-started-index-slug",
+              "slug": "/category/getting-started-index-slug",
+              "title": "Getting started index title (translated)",
+              "type": "generated-index",
+            },
             "type": "category",
           },
           Object {

package/src/__tests__/docs.test.ts

@@ -11,7 +11,8 @@ import {
   processDocMetadata,
   readVersionDocs,
   readDocFile,
-  handleNavigation,
+  addDocNavigation,
+  isConventionalDocIndex,
 } from '../docs';
 import {loadSidebars} from '../sidebars';
 import {readVersionsMetadata} from '../versions';
@@ -28,7 +29,8 @@ import type {LoadContext} from '@docusaurus/types';
 import {DEFAULT_PLUGIN_ID} from '@docusaurus/core/lib/constants';
 import {DEFAULT_OPTIONS} from '../options';
 import {Optional} from 'utility-types';
-import {posixPath} from '@docusaurus/utils';
+import {createSlugger, posixPath} from '@docusaurus/utils';
+import {createSidebarsUtils} from '../sidebars/utils';
 
 const fixtureDir = path.join(__dirname, '__fixtures__');
 
@@ -119,7 +121,7 @@ function createTestUtils({
 
   async function generateNavigation(
     docFiles: DocFile[],
-  ): Promise<[DocNavLink, DocNavLink][]> {
+  ): Promise<[DocNavLink | undefined, DocNavLink | undefined][]> {
     const rawDocs = await Promise.all(
       docFiles.map((docFile) =>
         processDocMetadata({
@@ -136,16 +138,19 @@ function createTestUtils({
       numberPrefixParser: options.numberPrefixParser,
       docs: rawDocs,
       version: versionMetadata,
-      options: {
+      sidebarOptions: {
         sidebarCollapsed: false,
         sidebarCollapsible: true,
       },
+      categoryLabelSlugger: createSlugger(),
     });
-    return handleNavigation(
+    const sidebarsUtils = createSidebarsUtils(sidebars);
+
+    return addDocNavigation(
       rawDocs,
-      sidebars,
+      sidebarsUtils,
       versionMetadata.sidebarFilePath as string,
-    ).docs.map((doc) => [doc.previous, doc.next]);
+    ).map((doc) => [doc.previous, doc.next]);
   }
 
   return {processDocFile, testMeta, testSlug, generateNavigation};
@@ -1022,3 +1027,113 @@ describe('versioned site', () => {
     });
   });
 });
+
+describe('isConventionalDocIndex', () => {
+  test('supports readme', () => {
+    expect(
+      isConventionalDocIndex({
+        sourceDirName: 'doesNotMatter',
+        source: 'readme.md',
+      }),
+    ).toEqual(true);
+    expect(
+      isConventionalDocIndex({
+        sourceDirName: 'doesNotMatter',
+        source: 'readme.mdx',
+      }),
+    ).toEqual(true);
+    expect(
+      isConventionalDocIndex({
+        sourceDirName: 'doesNotMatter',
+        source: 'README.md',
+      }),
+    ).toEqual(true);
+    expect(
+      isConventionalDocIndex({
+        sourceDirName: 'doesNotMatter',
+        source: 'parent/ReAdMe',
+      }),
+    ).toEqual(true);
+  });
+
+  test('supports index', () => {
+    expect(
+      isConventionalDocIndex({
+        sourceDirName: 'doesNotMatter',
+        source: 'index.md',
+      }),
+    ).toEqual(true);
+    expect(
+      isConventionalDocIndex({
+        sourceDirName: 'doesNotMatter',
+        source: 'index.mdx',
+      }),
+    ).toEqual(true);
+    expect(
+      isConventionalDocIndex({
+        sourceDirName: 'doesNotMatter',
+        source: 'INDEX.md',
+      }),
+    ).toEqual(true);
+    expect(
+      isConventionalDocIndex({
+        sourceDirName: 'doesNotMatter',
+        source: 'parent/InDeX',
+      }),
+    ).toEqual(true);
+  });
+
+  test('supports <categoryName>/<categoryName>.md', () => {
+    expect(
+      isConventionalDocIndex({
+        sourceDirName: 'someCategory',
+        source: 'someCategory',
+      }),
+    ).toEqual(true);
+    expect(
+      isConventionalDocIndex({
+        sourceDirName: 'someCategory',
+        source: 'someCategory.md',
+      }),
+    ).toEqual(true);
+    expect(
+      isConventionalDocIndex({
+        sourceDirName: 'someCategory',
+        source: 'someCategory.mdx',
+      }),
+    ).toEqual(true);
+    expect(
+      isConventionalDocIndex({
+        sourceDirName: 'some_category',
+        source: 'SOME_CATEGORY.md',
+      }),
+    ).toEqual(true);
+    expect(
+      isConventionalDocIndex({
+        sourceDirName: 'some_category',
+        source: 'parent/some_category',
+      }),
+    ).toEqual(true);
+  });
+
+  test('reject other cases', () => {
+    expect(
+      isConventionalDocIndex({
+        sourceDirName: 'someCategory',
+        source: 'some_Category',
+      }),
+    ).toEqual(false);
+    expect(
+      isConventionalDocIndex({
+        sourceDirName: 'doesNotMatter',
+        source: 'read_me',
+      }),
+    ).toEqual(false);
+    expect(
+      isConventionalDocIndex({
+        sourceDirName: 'doesNotMatter',
+        source: 'the index',
+      }),
+    ).toEqual(false);
+  });
+});

package/src/__tests__/index.test.ts

@@ -619,6 +619,32 @@ describe('versioned website', () => {
         {label: 'barTag 3', permalink: '/docs/next/tags/barTag-3-permalink'},
       ],
     });
+    expect(getDocById(version101, 'foo/bar')).toEqual({
+      ...defaultDocMetadata,
+      id: 'version-1.0.1/foo/bar',
+      unversionedId: 'foo/bar',
+      sourceDirName: 'foo',
+      isDocsHomePage: false,
+      permalink: '/docs/foo/bar',
+      slug: '/foo/bar',
+      source: path.posix.join(
+        '@site',
+        posixPath(path.relative(siteDir, version101.contentPath)),
+        'foo',
+        'bar.md',
+      ),
+      title: 'bar',
+      description: 'Bar 1.0.1 !',
+      frontMatter: {},
+      version: '1.0.1',
+      sidebar: 'VersionedSideBarNameDoesNotMatter/docs',
+      next: {
+        title: 'hello',
+        permalink: '/docs/',
+      },
+      tags: [],
+    });
+
     expect(getDocById(currentVersion, 'hello')).toEqual({
       ...defaultDocMetadata,
       id: 'hello',
@@ -659,7 +685,7 @@ describe('versioned website', () => {
       description: 'Hello 1.0.1 !',
       frontMatter: {},
       version: '1.0.1',
-      sidebar: 'version-1.0.1/docs',
+      sidebar: 'VersionedSideBarNameDoesNotMatter/docs',
       previous: {
         title: 'bar',
         permalink: '/docs/foo/bar',

package/src/__tests__/options.test.ts

@@ -51,6 +51,8 @@ describe('normalizeDocsPluginOptions', () => {
       docItemComponent: '@theme/DocItem',
       docTagDocListComponent: '@theme/DocTagDocListPage',
       docTagsListComponent: '@theme/DocTagsListPage',
+      docCategoryGeneratedIndexComponent:
+        '@theme/DocCategoryGeneratedIndexPage',
       remarkPlugins: [markdownPluginsObjectStub],
       rehypePlugins: [markdownPluginsFunctionStub],
       beforeDefaultRehypePlugins: [],

package/src/__tests__/slug.test.ts

@@ -9,24 +9,92 @@ import getSlug from '../slug';
 
 describe('getSlug', () => {
   test('should default to dirname/id', () => {
-    expect(getSlug({baseID: 'doc', dirName: '/dir'})).toEqual('/dir/doc');
-    expect(getSlug({baseID: 'doc', dirName: '/dir/subdir'})).toEqual(
-      '/dir/subdir/doc',
-    );
+    expect(
+      getSlug({
+        baseID: 'doc',
+        source: '@site/docs/dir/doc.md',
+        sourceDirName: '/dir',
+      }),
+    ).toEqual('/dir/doc');
+    expect(
+      getSlug({
+        baseID: 'doc',
+        source: '@site/docs/dir/subdir/doc.md',
+        sourceDirName: '/dir/subdir',
+      }),
+    ).toEqual('/dir/subdir/doc');
+  });
+
+  test('should handle conventional doc indexes', () => {
+    expect(
+      getSlug({
+        baseID: 'doc',
+        source: '@site/docs/dir/subdir/index.md',
+        sourceDirName: '/dir/subdir',
+      }),
+    ).toEqual('/dir/subdir/');
+    expect(
+      getSlug({
+        baseID: 'doc',
+        source: '@site/docs/dir/subdir/inDEx.mdx',
+        sourceDirName: '/dir/subdir',
+      }),
+    ).toEqual('/dir/subdir/');
+    expect(
+      getSlug({
+        baseID: 'doc',
+        source: '@site/docs/dir/subdir/readme.md',
+        sourceDirName: '/dir/subdir',
+      }),
+    ).toEqual('/dir/subdir/');
+    expect(
+      getSlug({
+        baseID: 'doc',
+        source: '@site/docs/dir/subdir/reADMe.mdx',
+        sourceDirName: '/dir/subdir',
+      }),
+    ).toEqual('/dir/subdir/');
+    expect(
+      getSlug({
+        baseID: 'doc',
+        source: '@site/docs/dir/subdir/subdir.md',
+        sourceDirName: '/dir/subdir',
+      }),
+    ).toEqual('/dir/subdir/');
+    expect(
+      getSlug({
+        baseID: 'doc',
+        source: '@site/docs/dir/subdir/suBDir.mdx',
+        sourceDirName: '/dir/subdir',
+      }),
+    ).toEqual('/dir/subdir/');
+  });
+
+  test('should ignore conventional doc index when explicit slug frontmatter is provided', () => {
+    expect(
+      getSlug({
+        baseID: 'doc',
+        source: '@site/docs/dir/subdir/index.md',
+        sourceDirName: '/dir/subdir',
+        frontmatterSlug: '/my/frontMatterSlug',
+      }),
+    ).toEqual('/my/frontMatterSlug');
   });
 
   test('can strip dir number prefixes', () => {
     expect(
       getSlug({
         baseID: 'doc',
-        dirName: '/001-dir1/002-dir2',
+        source: '@site/docs/001-dir1/002-dir2/doc.md',
+        sourceDirName: '/001-dir1/002-dir2',
         stripDirNumberPrefixes: true,
       }),
     ).toEqual('/dir1/dir2/doc');
     expect(
       getSlug({
         baseID: 'doc',
-        dirName: '/001-dir1/002-dir2',
+        source: '@site/docs/001-dir1/002-dir2/doc.md',
+        sourceDirName: '/001-dir1/002-dir2',
         stripDirNumberPrefixes: false,
       }),
     ).toEqual('/001-dir1/002-dir2/doc');
@@ -35,26 +103,45 @@ describe('getSlug', () => {
   // See https://github.com/facebook/docusaurus/issues/3223
   test('should handle special chars in doc path', () => {
     expect(
-      getSlug({baseID: 'my dôc', dirName: '/dir with spâce/hey $hello'}),
+      getSlug({
+        baseID: 'my dôc',
+        source: '@site/docs/dir with spâce/hey $hello/doc.md',
+        sourceDirName: '/dir with spâce/hey $hello',
+      }),
     ).toEqual('/dir with spâce/hey $hello/my dôc');
   });
 
   test('should handle current dir', () => {
-    expect(getSlug({baseID: 'doc', dirName: '.'})).toEqual('/doc');
-    expect(getSlug({baseID: 'doc', dirName: '/'})).toEqual('/doc');
+    expect(
+      getSlug({baseID: 'doc', source: '@site/docs/doc.md', sourceDirName: '.'}),
+    ).toEqual('/doc');
+    expect(
+      getSlug({baseID: 'doc', source: '@site/docs/doc.md', sourceDirName: '/'}),
+    ).toEqual('/doc');
   });
 
   test('should resolve absolute slug frontmatter', () => {
     expect(
-      getSlug({baseID: 'any', dirName: '.', frontmatterSlug: '/abc/def'}),
+      getSlug({
+        baseID: 'any',
+        source: '@site/docs/doc.md',
+        sourceDirName: '.',
+        frontmatterSlug: '/abc/def',
+      }),
     ).toEqual('/abc/def');
     expect(
-      getSlug({baseID: 'any', dirName: './any', frontmatterSlug: '/abc/def'}),
+      getSlug({
+        baseID: 'any',
+        source: '@site/docs/any/doc.md',
+        sourceDirName: './any',
+        frontmatterSlug: '/abc/def',
+      }),
     ).toEqual('/abc/def');
     expect(
       getSlug({
         baseID: 'any',
-        dirName: './any/any',
+        source: '@site/docs/any/any/doc.md',
+        sourceDirName: './any/any',
         frontmatterSlug: '/abc/def',
       }),
     ).toEqual('/abc/def');
@@ -62,46 +149,66 @@ describe('getSlug', () => {
 
   test('should resolve relative slug frontmatter', () => {
     expect(
-      getSlug({baseID: 'any', dirName: '.', frontmatterSlug: 'abc/def'}),
+      getSlug({
+        baseID: 'any',
+        source: '@site/docs/doc.md',
+        sourceDirName: '.',
+        frontmatterSlug: 'abc/def',
+      }),
     ).toEqual('/abc/def');
     expect(
-      getSlug({baseID: 'any', dirName: '/dir', frontmatterSlug: 'abc/def'}),
+      getSlug({
+        baseID: 'any',
+        source: '@site/docs/dir/doc.md',
+        sourceDirName: '/dir',
+        frontmatterSlug: 'abc/def',
+      }),
     ).toEqual('/dir/abc/def');
     expect(
       getSlug({
         baseID: 'any',
-        dirName: 'unslashedDir',
+        source: '@site/docs/unslashedDir/doc.md',
+        sourceDirName: 'unslashedDir',
         frontmatterSlug: 'abc/def',
       }),
     ).toEqual('/unslashedDir/abc/def');
     expect(
       getSlug({
         baseID: 'any',
-        dirName: 'dir/subdir',
+        source: '@site/docs/dir/subdir/doc.md',
+        sourceDirName: 'dir/subdir',
         frontmatterSlug: 'abc/def',
       }),
     ).toEqual('/dir/subdir/abc/def');
     expect(
-      getSlug({baseID: 'any', dirName: '/dir', frontmatterSlug: './abc/def'}),
+      getSlug({
+        baseID: 'any',
+        source: '@site/docs/dir/doc.md',
+        sourceDirName: '/dir',
+        frontmatterSlug: './abc/def',
+      }),
     ).toEqual('/dir/abc/def');
     expect(
       getSlug({
         baseID: 'any',
-        dirName: '/dir',
+        source: '@site/docs/dir/doc.md',
+        sourceDirName: '/dir',
         frontmatterSlug: './abc/../def',
       }),
     ).toEqual('/dir/def');
     expect(
       getSlug({
         baseID: 'any',
-        dirName: '/dir/subdir',
+        source: '@site/docs/dir/subdir/doc.md',
+        sourceDirName: '/dir/subdir',
         frontmatterSlug: '../abc/def',
       }),
     ).toEqual('/dir/abc/def');
     expect(
       getSlug({
         baseID: 'any',
-        dirName: '/dir/subdir',
+        source: '@site/docs/dir/subdirdoc.md',
+        sourceDirName: '/dir/subdir',
         frontmatterSlug: '../../../../../abc/../def',
       }),
     ).toEqual('/def');

package/src/__tests__/translations.test.ts

@@ -68,6 +68,13 @@ function createSampleVersion(
           type: 'category',
           label: 'Getting started',
           collapsed: false,
+          link: {
+            type: 'generated-index',
+            slug: '/category/getting-started-index-slug',
+            permalink: '/docs/category/getting-started-index-slug',
+            title: 'Getting started index title',
+            description: 'Getting started index description',
+          },
           items: [
             {
               type: 'doc',

package/src/categoryGeneratedIndex.ts

@@ -0,0 +1,57 @@
+/**
+ * Copyright (c) Facebook, Inc. and its affiliates.
+ *
+ * This source code is licensed under the MIT license found in the
+ * LICENSE file in the root directory of this source tree.
+ */
+
+import {CategoryGeneratedIndexMetadata, DocMetadataBase} from './types';
+import {SidebarItemCategoryWithGeneratedIndex} from './sidebars/types';
+import {SidebarsUtils, toNavigationLink} from './sidebars/utils';
+import {createDocsByIdIndex} from './docs';
+
+function getCategoryGeneratedIndexMetadata({
+  category,
+  sidebarsUtils,
+  docsById,
+}: {
+  category: SidebarItemCategoryWithGeneratedIndex;
+  sidebarsUtils: SidebarsUtils;
+  docsById: Record<string, DocMetadataBase>;
+}): CategoryGeneratedIndexMetadata {
+  const {sidebarName, previous, next} =
+    sidebarsUtils.getCategoryGeneratedIndexNavigation(category.link.permalink);
+  if (!sidebarName) {
+    throw new Error('unexpected');
+  }
+
+  return {
+    title: category.link.title ?? category.label,
+    description: category.link.description,
+    slug: category.link.slug,
+    permalink: category.link.permalink,
+    sidebar: sidebarName,
+    previous: toNavigationLink(previous, docsById),
+    next: toNavigationLink(next, docsById),
+  };
+}
+
+export function getCategoryGeneratedIndexMetadataList({
+  docs,
+  sidebarsUtils,
+}: {
+  sidebarsUtils: SidebarsUtils;
+  docs: DocMetadataBase[];
+}): CategoryGeneratedIndexMetadata[] {
+  const docsById = createDocsByIdIndex(docs);
+
+  const categoryGeneratedIndexItems =
+    sidebarsUtils.getCategoryGeneratedIndexList();
+  return categoryGeneratedIndexItems.map((category) =>
+    getCategoryGeneratedIndexMetadata({
+      category,
+      sidebarsUtils,
+      docsById,
+    }),
+  );
+}

package/src/cli.ts

@@ -13,9 +13,7 @@ import {
 import fs from 'fs-extra';
 import path from 'path';
 import type {PathOptions, SidebarOptions} from './types';
-import {transformSidebarItems} from './sidebars/utils';
-import type {SidebarItem, NormalizedSidebars, Sidebar} from './sidebars/types';
-import {loadUnprocessedSidebars, resolveSidebarPathOption} from './sidebars';
+import {loadSidebarsFile, resolveSidebarPathOption} from './sidebars';
 import {DEFAULT_PLUGIN_ID} from '@docusaurus/core/lib/constants';
 
 function createVersionedSidebarFile({
@@ -23,47 +21,20 @@ function createVersionedSidebarFile({
   pluginId,
   sidebarPath,
   version,
-  options,
 }: {
   siteDir: string;
   pluginId: string;
   sidebarPath: string | false | undefined;
   version: string;
-  options: SidebarOptions;
 }) {
   // Load current sidebar and create a new versioned sidebars file (if needed).
-  const loadedSidebars = loadUnprocessedSidebars(sidebarPath, options);
+  // Note: we don't need the sidebars file to be normalized: it's ok to let plugin option changes to impact older, versioned sidebars
+  const sidebars = loadSidebarsFile(sidebarPath);
 
   // Do not create a useless versioned sidebars file if sidebars file is empty or sidebars are disabled/false)
-  const shouldCreateVersionedSidebarFile =
-    Object.keys(loadedSidebars).length > 0;
+  const shouldCreateVersionedSidebarFile = Object.keys(sidebars).length > 0;
 
   if (shouldCreateVersionedSidebarFile) {
-    // TODO @slorber: this "version prefix" in versioned sidebars looks like a bad idea to me
-    // TODO try to get rid of it
-    // Transform id in original sidebar to versioned id.
-    const prependVersion = (item: SidebarItem): SidebarItem => {
-      if (item.type === 'ref' || item.type === 'doc') {
-        return {
-          type: item.type,
-          id: `version-${version}/${item.id}`,
-        };
-      }
-      return item;
-    };
-
-    const versionedSidebar = Object.entries(loadedSidebars).reduce(
-      (acc: NormalizedSidebars, [sidebarId, sidebar]) => {
-        const versionedId = `version-${version}/${sidebarId}`;
-        acc[versionedId] = transformSidebarItems(
-          sidebar as Sidebar,
-          prependVersion,
-        );
-        return acc;
-      },
-      {},
-    );
-
     const versionedSidebarsDir = getVersionedSidebarsDirPath(siteDir, pluginId);
     const newSidebarFile = path.join(
       versionedSidebarsDir,
@@ -72,7 +43,7 @@ function createVersionedSidebarFile({
     fs.ensureDirSync(path.dirname(newSidebarFile));
     fs.writeFileSync(
       newSidebarFile,
-      `${JSON.stringify(versionedSidebar, null, 2)}\n`,
+      `${JSON.stringify(sidebars, null, 2)}\n`,
       'utf8',
     );
   }
@@ -155,7 +126,6 @@ export function cliDocsVersionCommand(
     pluginId,
     version,
     sidebarPath: resolveSidebarPathOption(siteDir, sidebarPath),
-    options,
   });
 
   // Update versions.json file.