@docusaurus/plugin-content-docs 2.0.0-beta.15d451942 → 2.0.0-beta.18

package/src/docs.ts

@@ -7,6 +7,7 @@
 
 import path from 'path';
 import fs from 'fs-extra';
+import logger from '@docusaurus/logger';
 import {
   aliasedSitePath,
   getEditUrl,
@@ -14,24 +15,34 @@ import {
   normalizeUrl,
   parseMarkdownString,
   posixPath,
+  Globby,
+  normalizeFrontMatterTags,
 } from '@docusaurus/utils';
-import {LoadContext} from '@docusaurus/types';
+import type {LoadContext} from '@docusaurus/types';
 
 import {getFileLastUpdate} from './lastUpdate';
-import {
+import type {
   DocFile,
   DocMetadataBase,
+  DocMetadata,
+  DocNavLink,
   LastUpdateData,
-  MetadataOptions,
-  PluginOptions,
   VersionMetadata,
+  LoadedVersion,
 } from './types';
 import getSlug from './slug';
 import {CURRENT_VERSION_NAME} from './constants';
-import globby from 'globby';
 import {getDocsDirPaths} from './versions';
 import {stripPathNumberPrefixes} from './numberPrefix';
-import {validateDocFrontMatter} from './docFrontMatter';
+import {validateDocFrontMatter} from './frontMatter';
+import type {SidebarsUtils} from './sidebars/utils';
+import {toDocNavigationLink, toNavigationLink} from './sidebars/utils';
+import type {
+  MetadataOptions,
+  PluginOptions,
+  CategoryIndexMatcher,
+  CategoryIndexMatcherParam,
+} from '@docusaurus/plugin-content-docs';
 
 type LastUpdateOptions = Pick<
   PluginOptions,
@@ -91,18 +102,19 @@ export async function readVersionDocs(
   versionMetadata: VersionMetadata,
   options: Pick<
     PluginOptions,
-    'include' | 'showLastUpdateAuthor' | 'showLastUpdateTime'
+    'include' | 'exclude' | 'showLastUpdateAuthor' | 'showLastUpdateTime'
   >,
 ): Promise<DocFile[]> {
-  const sources = await globby(options.include, {
+  const sources = await Globby(options.include, {
     cwd: versionMetadata.contentPath,
+    ignore: options.exclude,
   });
   return Promise.all(
     sources.map((source) => readDocFile(versionMetadata, source, options)),
   );
 }
 
-export function processDocMetadata({
+function doProcessDocMetadata({
   docFile,
   versionMetadata,
   context,
@@ -114,7 +126,6 @@ export function processDocMetadata({
   options: MetadataOptions;
 }): DocMetadataBase {
   const {source, content, lastUpdate, contentPath, filePath} = docFile;
-  const {homePageId} = options;
   const {siteDir, i18n} = context;
 
   const {
@@ -125,12 +136,12 @@ export function processDocMetadata({
   const frontMatter = validateDocFrontMatter(unsafeFrontMatter);
 
   const {
-    sidebar_label: sidebarLabel,
     custom_edit_url: customEditURL,
 
-    // Strip number prefixes by default (01-MyFolder/01-MyDoc.md => MyFolder/MyDoc) by default,
-    // but allow to disable this behavior with frontmatterr
-    parse_number_prefixes = true,
+    // Strip number prefixes by default
+    // (01-MyFolder/01-MyDoc.md => MyFolder/MyDoc)
+    // but allow to disable this behavior with front matter
+    parse_number_prefixes: parseNumberPrefixes = true,
   } = frontMatter;
 
   // ex: api/plugins/myDoc -> myDoc
@@ -144,16 +155,17 @@ export function processDocMetadata({
   // ex: myDoc -> .
   const sourceDirName = path.dirname(source);
 
-  const {filename: unprefixedFileName, numberPrefix} = parse_number_prefixes
+  const {filename: unprefixedFileName, numberPrefix} = parseNumberPrefixes
     ? options.numberPrefixParser(sourceFileNameWithoutExtension)
     : {filename: sourceFileNameWithoutExtension, numberPrefix: undefined};
 
   const baseID: string = frontMatter.id ?? unprefixedFileName;
   if (baseID.includes('/')) {
-    throw new Error(`Document id [${baseID}] cannot include "/".`);
+    throw new Error(`Document id "${baseID}" cannot include slash.`);
   }
 
-  // For autogenerated sidebars, sidebar position can come from filename number prefix or frontmatter
+  // For autogenerated sidebars, sidebar position can come from filename number
+  // prefix or front matter
   const sidebarPosition: number | undefined =
     frontMatter.sidebar_position ?? numberPrefix;
 
@@ -166,13 +178,13 @@ export function processDocMetadata({
       : `version-${versionMetadata.versionName}`;
 
   // TODO legacy retrocompatibility
-  // I think it's bad to affect the frontmatter id with the dirname?
+  // I think it's bad to affect the front matter id with the dirname?
   function computeDirNameIdPrefix() {
     if (sourceDirName === '.') {
       return undefined;
     }
     // Eventually remove the number prefixes from intermediate directories
-    return parse_number_prefixes
+    return parseNumberPrefixes
       ? stripPathNumberPrefixes(sourceDirName, options.numberPrefixParser)
       : sourceDirName;
   }
@@ -185,29 +197,19 @@ export function processDocMetadata({
   // 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');
-  if (frontMatter.slug && isDocsHomePage) {
-    throw new Error(
-      `The docs homepage (homePageId=${homePageId}) is not allowed to have a frontmatter slug=${frontMatter.slug} => you have to choose either homePageId or slug, not both`,
-    );
-  }
-
-  const docSlug = isDocsHomePage
-    ? '/'
-    : getSlug({
-        baseID,
-        dirName: sourceDirName,
-        frontmatterSlug: frontMatter.slug,
-        stripDirNumberPrefixes: parse_number_prefixes,
-        numberPrefixParser: options.numberPrefixParser,
-      });
+  const docSlug = getSlug({
+    baseID,
+    source,
+    sourceDirName,
+    frontMatterSlug: frontMatter.slug,
+    stripDirNumberPrefixes: parseNumberPrefixes,
+    numberPrefixParser: options.numberPrefixParser,
+  });
 
-  // TODO expose both headingTitle+metaTitle to theme?
-  // Different fallbacks order on purpose!
-  // See https://github.com/facebook/docusaurus/issues/4665#issuecomment-825831367
-  const headingTitle: string = contentTitle ?? frontMatter.title ?? baseID;
-  // const metaTitle: string = frontMatter.title ?? contentTitle  ?? baseID;
+  // Note: the title is used by default for page title, sidebar label,
+  // pagination buttons... frontMatter.title should be used in priority over
+  // contentTitle (because it can contain markdown/JSX syntax)
+  const title: string = frontMatter.title ?? contentTitle ?? baseID;
 
   const description: string = frontMatter.description ?? excerpt ?? '';
 
@@ -233,9 +235,8 @@ export function processDocMetadata({
           ? versionMetadata.versionEditUrlLocalized
           : versionMetadata.versionEditUrl;
       return getEditUrl(relativeFilePath, baseVersionEditUrl);
-    } else {
-      return undefined;
     }
+    return undefined;
   }
 
   // Assign all of object properties during instantiation (if possible) for
@@ -245,14 +246,14 @@ export function processDocMetadata({
   return {
     unversionedId,
     id,
-    isDocsHomePage,
-    title: headingTitle,
+    title,
     description,
     source: aliasedSitePath(filePath, siteDir),
     sourceDirName,
     slug: docSlug,
     permalink,
     editUrl: customEditURL !== undefined ? customEditURL : getDocEditUrl(),
+    tags: normalizeFrontMatterTags(versionMetadata.tagsPath, frontMatter.tags),
     version: versionMetadata.versionName,
     lastUpdatedBy: lastUpdate.lastUpdatedBy,
     lastUpdatedAt: lastUpdate.lastUpdatedAt,
@@ -261,8 +262,173 @@ export function processDocMetadata({
           lastUpdate.lastUpdatedAt * 1000,
         )
       : undefined,
-    sidebar_label: sidebarLabel,
     sidebarPosition,
     frontMatter,
   };
 }
+
+export function processDocMetadata(args: {
+  docFile: DocFile;
+  versionMetadata: VersionMetadata;
+  context: LoadContext;
+  options: MetadataOptions;
+}): DocMetadataBase {
+  try {
+    return doProcessDocMetadata(args);
+  } catch (err) {
+    logger.error`Can't process doc metadata for doc at path path=${args.docFile.filePath} in version name=${args.versionMetadata.versionName}`;
+    throw err;
+  }
+}
+
+export function addDocNavigation(
+  docsBase: DocMetadataBase[],
+  sidebarsUtils: SidebarsUtils,
+  sidebarFilePath: string,
+): LoadedVersion['docs'] {
+  const docsById = createDocsByIdIndex(docsBase);
+
+  sidebarsUtils.checkSidebarsDocIds(
+    docsBase.flatMap(getDocIds),
+    sidebarFilePath,
+  );
+
+  // Add sidebar/next/previous to the docs
+  function addNavData(doc: DocMetadataBase): DocMetadata {
+    const navigation = sidebarsUtils.getDocNavigation(
+      doc.unversionedId,
+      doc.id,
+      doc.frontMatter.displayed_sidebar,
+    );
+
+    const toNavigationLinkByDocId = (
+      docId: string | null | undefined,
+      type: 'prev' | 'next',
+    ): DocNavLink | undefined => {
+      if (!docId) {
+        return undefined;
+      }
+      const navDoc = docsById[docId];
+      if (!navDoc) {
+        // This could only happen if user provided the ID through front matter
+        throw new Error(
+          `Error when loading ${doc.id} in ${doc.sourceDirName}: the pagination_${type} front matter points to a non-existent ID ${docId}.`,
+        );
+      }
+      return toDocNavigationLink(navDoc);
+    };
+
+    const previous =
+      doc.frontMatter.pagination_prev !== undefined
+        ? toNavigationLinkByDocId(doc.frontMatter.pagination_prev, 'prev')
+        : toNavigationLink(navigation.previous, docsById);
+    const next =
+      doc.frontMatter.pagination_next !== undefined
+        ? toNavigationLinkByDocId(doc.frontMatter.pagination_next, 'next')
+        : toNavigationLink(navigation.next, docsById);
+
+    return {...doc, sidebar: navigation.sidebarName, previous, next};
+  }
+
+  const docsWithNavigation = docsBase.map(addNavData);
+  // sort to ensure consistent output for tests
+  docsWithNavigation.sort((a, b) => a.id.localeCompare(b.id));
+  return docsWithNavigation;
+}
+
+/**
+ * The "main doc" is the "version entry point"
+ * We browse this doc by clicking on a version:
+ * - the "home" doc (at '/docs/')
+ * - the first doc of the first sidebar
+ * - a random doc (if no docs are in any sidebar... edge case)
+ */
+export function getMainDocId({
+  docs,
+  sidebarsUtils,
+}: {
+  docs: DocMetadataBase[];
+  sidebarsUtils: SidebarsUtils;
+}): string {
+  function getMainDoc(): DocMetadata {
+    const versionHomeDoc = docs.find((doc) => doc.slug === '/');
+    const firstDocIdOfFirstSidebar =
+      sidebarsUtils.getFirstDocIdOfFirstSidebar();
+    if (versionHomeDoc) {
+      return versionHomeDoc;
+    } else if (firstDocIdOfFirstSidebar) {
+      return docs.find(
+        (doc) =>
+          doc.id === firstDocIdOfFirstSidebar ||
+          doc.unversionedId === firstDocIdOfFirstSidebar,
+      )!;
+    }
+    return docs[0]!;
+  }
+
+  return getMainDoc().unversionedId;
+}
+
+// By convention, Docusaurus considers some docs are "indexes":
+// - index.md
+// - readme.md
+// - <folder>/<folder>.md
+//
+// This function is the default implementation of this convention
+//
+// Those index docs produce a different behavior
+// - Slugs do not end with a weird "/index" suffix
+// - Auto-generated sidebar categories link to them as intro
+export const isCategoryIndex: CategoryIndexMatcher = ({
+  fileName,
+  directories,
+}): boolean => {
+  const eligibleDocIndexNames = [
+    'index',
+    'readme',
+    directories[0]?.toLowerCase(),
+  ];
+  return eligibleDocIndexNames.includes(fileName.toLowerCase());
+};
+
+/**
+ * `guides/sidebar/autogenerated.md` ->
+ *   `'autogenerated', '.md', ['sidebar', 'guides']`
+ */
+export function toCategoryIndexMatcherParam({
+  source,
+  sourceDirName,
+}: Pick<
+  DocMetadataBase,
+  'source' | 'sourceDirName'
+>): CategoryIndexMatcherParam {
+  // source + sourceDirName are always posix-style
+  return {
+    fileName: path.posix.parse(source).name,
+    extension: path.posix.parse(source).ext,
+    directories: sourceDirName.split(path.posix.sep).reverse(),
+  };
+}
+
+// Return both doc ids
+// TODO legacy retro-compatibility due to old versioned sidebars using
+// versioned doc ids ("id" should be removed & "versionedId" should be renamed
+// to "id")
+export function getDocIds(doc: DocMetadataBase): [string, string] {
+  return [doc.unversionedId, doc.id];
+}
+
+// docs are indexed by both versioned and unversioned ids at the same time
+// TODO legacy retro-compatibility due to old versioned sidebars using
+// versioned doc ids ("id" should be removed & "versionedId" should be renamed
+// to "id")
+export function createDocsByIdIndex<
+  Doc extends {id: string; unversionedId: string},
+>(docs: Doc[]): {[docId: string]: Doc} {
+  return Object.fromEntries(
+    docs.flatMap((doc) => [
+      [doc.unversionedId, doc],
+      [doc.id, doc],
+    ]),
+  );
+}

package/src/{docFrontMatter.ts → frontMatter.ts}

@@ -5,30 +5,17 @@
  * LICENSE file in the root directory of this source tree.
  */
 
-/* eslint-disable camelcase */
-
 import {
-  JoiFrontMatter as Joi, // Custom instance for frontmatter
+  JoiFrontMatter as Joi, // Custom instance for front matter
+  URISchema,
+  FrontMatterTagsSchema,
+  FrontMatterTOCHeadingLevels,
   validateFrontMatter,
 } from '@docusaurus/utils-validation';
-
-export type DocFrontMatter = {
-  id?: string;
-  title?: string;
-  hide_title?: boolean;
-  hide_table_of_contents?: boolean;
-  keywords?: string[];
-  image?: string;
-  description?: string;
-  slug?: string;
-  sidebar_label?: string;
-  sidebar_position?: number;
-  custom_edit_url?: string | null;
-  parse_number_prefixes?: boolean;
-};
+import type {DocFrontMatter} from './types';
 
 // NOTE: we don't add any default value on purpose here
-// We don't want default values to magically appear in doc metadatas and props
+// We don't want default values to magically appear in doc metadata and props
 // While the user did not provide those values explicitly
 // We use default values in code instead
 const DocFrontMatterSchema = Joi.object<DocFrontMatter>({
@@ -37,17 +24,25 @@ const DocFrontMatterSchema = Joi.object<DocFrontMatter>({
   hide_title: Joi.boolean(),
   hide_table_of_contents: Joi.boolean(),
   keywords: Joi.array().items(Joi.string().required()),
-  image: Joi.string().uri({allowRelative: false}),
-  description: Joi.string().allow(''), // see  https://github.com/facebook/docusaurus/issues/4591#issuecomment-822372398
+  image: URISchema,
+  description: Joi.string().allow(''), // see https://github.com/facebook/docusaurus/issues/4591#issuecomment-822372398
   slug: Joi.string(),
   sidebar_label: Joi.string(),
-  sidebar_position: Joi.number().min(0),
-  custom_edit_url: Joi.string().uri({allowRelative: true}).allow('', null),
+  sidebar_position: Joi.number(),
+  sidebar_class_name: Joi.string(),
+  sidebar_custom_props: Joi.object().unknown(),
+  displayed_sidebar: Joi.string().allow(null),
+  tags: FrontMatterTagsSchema,
+  pagination_label: Joi.string(),
+  custom_edit_url: URISchema.allow('', null),
   parse_number_prefixes: Joi.boolean(),
+  pagination_next: Joi.string().allow(null),
+  pagination_prev: Joi.string().allow(null),
+  ...FrontMatterTOCHeadingLevels,
 }).unknown();
 
-export function validateDocFrontMatter(
-  frontMatter: Record<string, unknown>,
-): DocFrontMatter {
+export function validateDocFrontMatter(frontMatter: {
+  [key: string]: unknown;
+}): DocFrontMatter {
   return validateFrontMatter(frontMatter, DocFrontMatterSchema);
 }

package/src/globalData.ts

@@ -5,9 +5,21 @@
  * LICENSE file in the root directory of this source tree.
  */
 
-import {DocMetadata, GlobalDoc, LoadedVersion, GlobalVersion} from './types';
+import _ from 'lodash';
+import type {Sidebars} from './sidebars/types';
+import {createSidebarsUtils} from './sidebars/utils';
+import type {
+  CategoryGeneratedIndexMetadata,
+  DocMetadata,
+  LoadedVersion,
+} from './types';
+import type {
+  GlobalVersion,
+  GlobalSidebar,
+  GlobalDoc,
+} from '@docusaurus/plugin-content-docs/client';
 
-export function toGlobalDataDoc(doc: DocMetadata): GlobalDoc {
+function toGlobalDataDoc(doc: DocMetadata): GlobalDoc {
   return {
     id: doc.unversionedId,
     path: doc.permalink,
@@ -15,6 +27,41 @@ export function toGlobalDataDoc(doc: DocMetadata): GlobalDoc {
   };
 }
 
+function toGlobalDataGeneratedIndex(
+  doc: CategoryGeneratedIndexMetadata,
+): GlobalDoc {
+  return {
+    id: doc.slug,
+    path: doc.permalink,
+    sidebar: doc.sidebar,
+  };
+}
+
+function toGlobalSidebars(
+  sidebars: Sidebars,
+  version: LoadedVersion,
+): {[sidebarId: string]: GlobalSidebar} {
+  const {getFirstLink} = createSidebarsUtils(sidebars);
+  return _.mapValues(sidebars, (sidebar, sidebarId) => {
+    const firstLink = getFirstLink(sidebarId);
+    if (!firstLink) {
+      return {};
+    }
+    return {
+      link: {
+        path:
+          firstLink.type === 'generated-index'
+            ? firstLink.permalink
+            : version.docs.find(
+                (doc) =>
+                  doc.id === firstLink.id || doc.unversionedId === firstLink.id,
+              )!.permalink,
+        label: firstLink.label,
+      },
+    };
+  });
+}
+
 export function toGlobalDataVersion(version: LoadedVersion): GlobalVersion {
   return {
     name: version.versionName,
@@ -22,6 +69,9 @@ export function toGlobalDataVersion(version: LoadedVersion): GlobalVersion {
     isLast: version.isLast,
     path: version.versionPath,
     mainDocId: version.mainDocId,
-    docs: version.docs.map(toGlobalDataDoc),
+    docs: version.docs
+      .map(toGlobalDataDoc)
+      .concat(version.categoryGeneratedIndices.map(toGlobalDataGeneratedIndex)),
+    sidebars: toGlobalSidebars(version.sidebars, version),
   };
 }