@docusaurus/plugin-content-docs 2.0.0-beta.15a2b59f9 → 2.0.0-beta.17

package/src/client/docsClientUtils.ts

@@ -7,49 +7,37 @@
 
 import {matchPath} from '@docusaurus/router';
 
-import {GlobalPluginData, GlobalVersion, GlobalDoc} from '../types';
+import type {
+  GlobalPluginData,
+  GlobalVersion,
+  GlobalDoc,
+  GetActivePluginOptions,
+  ActivePlugin,
+  ActiveDocContext,
+  DocVersionSuggestions,
+} from '@docusaurus/plugin-content-docs/client';
 
 // This code is not part of the api surface, not in ./theme on purpose
 
-// Short/convenient type aliases
-type Version = GlobalVersion;
-type Doc = GlobalDoc;
-
-export type ActivePlugin = {
-  pluginId: string;
-  pluginData: GlobalPluginData;
-};
-
-export type GetActivePluginOptions = {failfast?: boolean};
-
 // get the data of the plugin that is currently "active"
 // ie the docs of that plugin are currently browsed
 // it is useful to support multiple docs plugin instances
-export function getActivePlugin(
-  allPluginDatas: Record<string, GlobalPluginData>,
-  pathname: string,
-  options: {failfast: true}, // use fail-fast option if you know for sure one plugin instance is active
-): ActivePlugin;
-export function getActivePlugin(
-  allPluginDatas: Record<string, GlobalPluginData>,
-  pathname: string,
-  options?: GetActivePluginOptions,
-): ActivePlugin | undefined;
-
 export function getActivePlugin(
   allPluginDatas: Record<string, GlobalPluginData>,
   pathname: string,
   options: GetActivePluginOptions = {},
 ): ActivePlugin | undefined {
-  const activeEntry = Object.entries(allPluginDatas).find(
-    ([_id, pluginData]) => {
-      return !!matchPath(pathname, {
-        path: pluginData.path,
-        exact: false,
-        strict: false,
-      });
-    },
-  );
+  const activeEntry = Object.entries(allPluginDatas)
+    // Route sorting: '/android/foo' should match '/android' instead of '/'
+    .sort((a, b) => b[1].path.localeCompare(a[1].path))
+    .find(
+      ([, pluginData]) =>
+        !!matchPath(pathname, {
+          path: pluginData.path,
+          exact: false,
+          strict: false,
+        }),
+    );
 
   const activePlugin: ActivePlugin | undefined = activeEntry
     ? {pluginId: activeEntry[0], pluginData: activeEntry[1]}
@@ -68,36 +56,30 @@ export function getActivePlugin(
   return activePlugin;
 }
 
-export type ActiveDocContext = {
-  activeVersion?: Version;
-  activeDoc?: Doc;
-  alternateDocVersions: Record<string, Doc>;
-};
-
-export const getLatestVersion = (data: GlobalPluginData): Version => {
-  return data.versions.find((version) => version.isLast)!;
-};
+export const getLatestVersion = (data: GlobalPluginData): GlobalVersion =>
+  data.versions.find((version) => version.isLast)!;
 
 // Note: return undefined on doc-unrelated pages,
 // because there's no version currently considered as active
 export const getActiveVersion = (
   data: GlobalPluginData,
   pathname: string,
-): Version | undefined => {
+): GlobalVersion | undefined => {
   const lastVersion = getLatestVersion(data);
   // Last version is a route like /docs/*,
-  // we need to try to match it last or it would match /docs/version-1.0/* as well
+  // we need to match it last or it would match /docs/version-1.0/* as well
   const orderedVersionsMetadata = [
     ...data.versions.filter((version) => version !== lastVersion),
     lastVersion,
   ];
-  return orderedVersionsMetadata.find((version) => {
-    return !!matchPath(pathname, {
-      path: version.path,
-      exact: false,
-      strict: false,
-    });
-  });
+  return orderedVersionsMetadata.find(
+    (version) =>
+      !!matchPath(pathname, {
+        path: version.path,
+        exact: false,
+        strict: false,
+      }),
+  );
 };
 
 export const getActiveDocContext = (
@@ -139,13 +121,6 @@ export const getActiveDocContext = (
   };
 };
 
-export type DocVersionSuggestions = {
-  // suggest the latest version
-  latestVersionSuggestion: GlobalVersion;
-  // suggest the same doc, in latest version (if exist)
-  latestDocSuggestion?: GlobalDoc;
-};
-
 export const getDocVersionSuggestions = (
   data: GlobalPluginData,
   pathname: string,

package/src/{theme/hooks/useDocs.ts → client/index.ts}

@@ -6,37 +6,38 @@
  */
 
 import {useLocation} from '@docusaurus/router';
-import useGlobalData, {
-  // useAllPluginInstancesData,
-  usePluginData,
-} from '@docusaurus/useGlobalData';
+import useGlobalData, {usePluginData} from '@docusaurus/useGlobalData';
 
-import {GlobalPluginData, GlobalVersion} from '../../types';
 import {
   getActivePlugin,
   getLatestVersion,
   getActiveVersion,
   getActiveDocContext,
   getDocVersionSuggestions,
+} from './docsClientUtils';
+import type {
+  GlobalPluginData,
+  GlobalVersion,
   ActivePlugin,
   ActiveDocContext,
   DocVersionSuggestions,
   GetActivePluginOptions,
-} from '../../client/docsClientUtils';
+} from '@docusaurus/plugin-content-docs/client';
 
-// Important to use a constant object to avoid React useEffect executions etc...,
+// Important to use a constant object to avoid React useEffect executions etc.
 // see https://github.com/facebook/docusaurus/issues/5089
 const StableEmptyObject = {};
 
-// Not using useAllPluginInstancesData() because in blog-only mode, docs hooks are still used by the theme
-// We need a fail-safe fallback when the docs plugin is not in use
+// Not using useAllPluginInstancesData() because in blog-only mode, docs hooks
+// are still used by the theme. We need a fail-safe fallback when the docs
+// plugin is not in use
 export const useAllDocsData = (): Record<string, GlobalPluginData> =>
-  // useAllPluginInstancesData('docusaurus-plugin-content-docs');
   useGlobalData()['docusaurus-plugin-content-docs'] ?? StableEmptyObject;
 
 export const useDocsData = (pluginId: string | undefined): GlobalPluginData =>
   usePluginData('docusaurus-plugin-content-docs', pluginId) as GlobalPluginData;
 
+// TODO this feature should be provided by docusaurus core
 export const useActivePlugin = (
   options: GetActivePluginOptions = {},
 ): ActivePlugin | undefined => {

package/src/docFrontMatter.ts

@@ -5,17 +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';
-import {DocFrontMatter} from './types';
+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>({
@@ -29,9 +29,16 @@ const DocFrontMatterSchema = Joi.object<DocFrontMatter>({
   slug: Joi.string(),
   sidebar_label: Joi.string(),
   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(

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,25 +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 chalk from 'chalk';
+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,
@@ -92,11 +102,12 @@ 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)),
@@ -115,7 +126,6 @@ function doProcessDocMetadata({
   options: MetadataOptions;
 }): DocMetadataBase {
   const {source, content, lastUpdate, contentPath, filePath} = docFile;
-  const {homePageId} = options;
   const {siteDir, i18n} = context;
 
   const {
@@ -128,10 +138,10 @@ function doProcessDocMetadata({
   const {
     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
-    // eslint-disable-next-line camelcase
-    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
@@ -145,8 +155,7 @@ function doProcessDocMetadata({
   // ex: myDoc -> .
   const sourceDirName = path.dirname(source);
 
-  // eslint-disable-next-line camelcase
-  const {filename: unprefixedFileName, numberPrefix} = parse_number_prefixes
+  const {filename: unprefixedFileName, numberPrefix} = parseNumberPrefixes
     ? options.numberPrefixParser(sourceFileNameWithoutExtension)
     : {filename: sourceFileNameWithoutExtension, numberPrefix: undefined};
 
@@ -155,7 +164,8 @@ function doProcessDocMetadata({
     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;
 
@@ -168,14 +178,13 @@ function doProcessDocMetadata({
       : `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
-    // eslint-disable-next-line camelcase
-    return parse_number_prefixes
+    return parseNumberPrefixes
       ? stripPathNumberPrefixes(sourceDirName, options.numberPrefixParser)
       : sourceDirName;
   }
@@ -188,26 +197,18 @@ function doProcessDocMetadata({
   // 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,
+  });
 
-  // 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)
+  // 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 ?? '';
@@ -234,9 +235,8 @@ function doProcessDocMetadata({
           ? versionMetadata.versionEditUrlLocalized
           : versionMetadata.versionEditUrl;
       return getEditUrl(relativeFilePath, baseVersionEditUrl);
-    } else {
-      return undefined;
     }
+    return undefined;
   }
 
   // Assign all of object properties during instantiation (if possible) for
@@ -246,7 +246,6 @@ function doProcessDocMetadata({
   return {
     unversionedId,
     id,
-    isDocsHomePage,
     title,
     description,
     source: aliasedSitePath(filePath, siteDir),
@@ -254,6 +253,7 @@ function doProcessDocMetadata({
     slug: docSlug,
     permalink,
     editUrl: customEditURL !== undefined ? customEditURL : getDocEditUrl(),
+    tags: normalizeFrontMatterTags(versionMetadata.tagsPath, frontMatter.tags),
     version: versionMetadata.versionName,
     lastUpdatedBy: lastUpdate.lastUpdatedBy,
     lastUpdatedAt: lastUpdate.lastUpdatedAt,
@@ -275,12 +275,178 @@ export function processDocMetadata(args: {
 }): DocMetadataBase {
   try {
     return doProcessDocMetadata(args);
-  } catch (e) {
-    console.error(
-      chalk.red(
-        `Can't process doc metadatas for doc at path "${args.docFile.filePath}" in version "${args.versionMetadata.versionName}"`,
-      ),
+  } 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,
     );
-    throw e;
+
+    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());
+};
+
+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(),
+  };
+}
+
+/**
+ * `guides/sidebar/autogenerated.md` ->
+ *   `'autogenerated', '.md', ['sidebar', 'guides']`
+ */
+export function splitPath(str: string): {
+  /**
+   * The list of directories, from lowest level to highest.
+   * If there's no dir name, directories is ['.']
+   */
+  directories: string[];
+  /** The file name, without extension */
+  fileName: string;
+  /** The extension, with a leading dot */
+  extension: string;
+} {
+  return {
+    fileName: path.parse(str).name,
+    extension: path.parse(str).ext,
+    directories: path.dirname(str).split(path.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[]): Record<string, Doc> {
+  return Object.fromEntries(
+    docs.flatMap((doc) => [
+      [doc.unversionedId, doc],
+      [doc.id, doc],
+    ]),
+  );
 }

package/src/globalData.ts

@@ -5,7 +5,20 @@
  * LICENSE file in the root directory of this source tree.
  */
 
-import {DocMetadata, GlobalDoc, LoadedVersion, GlobalVersion} from './types';
+import _ from 'lodash';
+import {normalizeUrl} from '@docusaurus/utils';
+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 {
   return {
@@ -15,6 +28,41 @@ export function toGlobalDataDoc(doc: DocMetadata): GlobalDoc {
   };
 }
 
+export function toGlobalDataGeneratedIndex(
+  doc: CategoryGeneratedIndexMetadata,
+): GlobalDoc {
+  return {
+    id: doc.slug,
+    path: doc.permalink,
+    sidebar: doc.sidebar,
+  };
+}
+
+export function toGlobalSidebars(
+  sidebars: Sidebars,
+  version: LoadedVersion,
+): Record<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'
+            ? normalizeUrl([version.versionPath, firstLink.slug])
+            : 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 +70,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),
   };
 }