@docusaurus/plugin-content-docs 2.0.0-beta.fc64c12e4 → 2.0.0

package/src/docs.ts

@@ -7,32 +7,41 @@
 
 import path from 'path';
 import fs from 'fs-extra';
+import logger from '@docusaurus/logger';
 import {
   aliasedSitePath,
   getEditUrl,
   getFolderContainingFile,
+  getContentPathList,
   normalizeUrl,
   parseMarkdownString,
   posixPath,
   Globby,
+  normalizeFrontMatterTags,
 } from '@docusaurus/utils';
-import {LoadContext} from '@docusaurus/types';
 
 import {getFileLastUpdate} from './lastUpdate';
-import {
-  DocFile,
-  DocMetadataBase,
-  LastUpdateData,
-  MetadataOptions,
-  PluginOptions,
-  VersionMetadata,
-} from './types';
 import getSlug from './slug';
 import {CURRENT_VERSION_NAME} from './constants';
-import {getDocsDirPaths} from './versions';
 import {stripPathNumberPrefixes} from './numberPrefix';
-import {validateDocFrontMatter} from './docFrontMatter';
-import chalk from 'chalk';
+import {validateDocFrontMatter} from './frontMatter';
+import {toDocNavigationLink, toNavigationLink} from './sidebars/utils';
+import type {
+  MetadataOptions,
+  PluginOptions,
+  CategoryIndexMatcher,
+  DocMetadataBase,
+  DocMetadata,
+  PropNavigationLink,
+  LastUpdateData,
+  VersionMetadata,
+  DocFrontMatter,
+  LoadedVersion,
+  FileChange,
+} from '@docusaurus/plugin-content-docs';
+import type {LoadContext} from '@docusaurus/types';
+import type {SidebarsUtils} from './sidebars/utils';
+import type {DocFile} from './types';
 
 type LastUpdateOptions = Pick<
   PluginOptions,
@@ -42,9 +51,21 @@ type LastUpdateOptions = Pick<
 async function readLastUpdateData(
   filePath: string,
   options: LastUpdateOptions,
+  lastUpdateFrontMatter: FileChange | undefined,
 ): Promise<LastUpdateData> {
   const {showLastUpdateAuthor, showLastUpdateTime} = options;
   if (showLastUpdateAuthor || showLastUpdateTime) {
+    const frontMatterTimestamp = lastUpdateFrontMatter?.date
+      ? new Date(lastUpdateFrontMatter.date).getTime() / 1000
+      : undefined;
+
+    if (lastUpdateFrontMatter?.author && lastUpdateFrontMatter.date) {
+      return {
+        lastUpdatedAt: frontMatterTimestamp,
+        lastUpdatedBy: lastUpdateFrontMatter.author,
+      };
+    }
+
     // Use fake data in dev for faster development.
     const fileLastUpdateData =
       process.env.NODE_ENV === 'production'
@@ -53,14 +74,16 @@ async function readLastUpdateData(
             author: 'Author',
             timestamp: 1539502055,
           };
-
-    if (fileLastUpdateData) {
-      const {author, timestamp} = fileLastUpdateData;
-      return {
-        lastUpdatedAt: showLastUpdateTime ? timestamp : undefined,
-        lastUpdatedBy: showLastUpdateAuthor ? author : undefined,
-      };
-    }
+    const {author, timestamp} = fileLastUpdateData ?? {};
+
+    return {
+      lastUpdatedBy: showLastUpdateAuthor
+        ? lastUpdateFrontMatter?.author ?? author
+        : undefined,
+      lastUpdatedAt: showLastUpdateTime
+        ? frontMatterTimestamp ?? timestamp
+        : undefined,
+    };
   }
 
   return {};
@@ -72,20 +95,16 @@ export async function readDocFile(
     'contentPath' | 'contentPathLocalized'
   >,
   source: string,
-  options: LastUpdateOptions,
 ): Promise<DocFile> {
   const contentPath = await getFolderContainingFile(
-    getDocsDirPaths(versionMetadata),
+    getContentPathList(versionMetadata),
     source,
   );
 
   const filePath = path.join(contentPath, source);
 
-  const [content, lastUpdate] = await Promise.all([
-    fs.readFile(filePath, 'utf-8'),
-    readLastUpdateData(filePath, options),
-  ]);
-  return {source, content, lastUpdate, contentPath, filePath};
+  const content = await fs.readFile(filePath, 'utf-8');
+  return {source, content, contentPath, filePath};
 }
 
 export async function readVersionDocs(
@@ -100,23 +119,37 @@ export async function readVersionDocs(
     ignore: options.exclude,
   });
   return Promise.all(
-    sources.map((source) => readDocFile(versionMetadata, source, options)),
+    sources.map((source) => readDocFile(versionMetadata, source)),
   );
 }
 
-function doProcessDocMetadata({
+export type DocEnv = 'production' | 'development';
+
+/** Docs with draft front matter are only considered draft in production. */
+function isDraftForEnvironment({
+  env,
+  frontMatter,
+}: {
+  frontMatter: DocFrontMatter;
+  env: DocEnv;
+}): boolean {
+  return (env === 'production' && frontMatter.draft) ?? false;
+}
+
+async function doProcessDocMetadata({
   docFile,
   versionMetadata,
   context,
   options,
+  env,
 }: {
   docFile: DocFile;
   versionMetadata: VersionMetadata;
   context: LoadContext;
   options: MetadataOptions;
-}): DocMetadataBase {
-  const {source, content, lastUpdate, contentPath, filePath} = docFile;
-  const {homePageId} = options;
+  env: DocEnv;
+}): Promise<DocMetadataBase> {
+  const {source, content, contentPath, filePath} = docFile;
   const {siteDir, i18n} = context;
 
   const {
@@ -129,25 +162,29 @@ 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,
+    last_update: lastUpdateFrontMatter,
   } = frontMatter;
 
-  // ex: api/plugins/myDoc -> myDoc
-  // ex: myDoc -> myDoc
+  const lastUpdate = await readLastUpdateData(
+    filePath,
+    options,
+    lastUpdateFrontMatter,
+  );
+
+  // E.g. api/plugins/myDoc -> myDoc; myDoc -> myDoc
   const sourceFileNameWithoutExtension = path.basename(
     source,
     path.extname(source),
   );
 
-  // ex: api/plugins/myDoc -> api/plugins
-  // ex: myDoc -> .
+  // E.g. api/plugins/myDoc -> api/plugins; 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};
 
@@ -156,7 +193,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;
 
@@ -169,14 +207,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;
   }
@@ -189,31 +226,23 @@ 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 ?? '';
 
-  const permalink = normalizeUrl([versionMetadata.versionPath, docSlug]);
+  const permalink = normalizeUrl([versionMetadata.path, docSlug]);
 
   function getDocEditUrl() {
     const relativeFilePath = path.relative(contentPath, filePath);
@@ -232,14 +261,30 @@ function doProcessDocMetadata({
       const isLocalized = contentPath === versionMetadata.contentPathLocalized;
       const baseVersionEditUrl =
         isLocalized && options.editLocalizedFiles
-          ? versionMetadata.versionEditUrlLocalized
-          : versionMetadata.versionEditUrl;
+          ? versionMetadata.editUrlLocalized
+          : versionMetadata.editUrl;
       return getEditUrl(relativeFilePath, baseVersionEditUrl);
-    } else {
-      return undefined;
     }
+    return undefined;
   }
 
+  const draft = isDraftForEnvironment({env, frontMatter});
+
+  const formatDate = (locale: string, date: Date, calendar: string): string => {
+    try {
+      return new Intl.DateTimeFormat(locale, {
+        day: 'numeric',
+        month: 'short',
+        year: 'numeric',
+        timeZone: 'UTC',
+        calendar,
+      }).format(date);
+    } catch (err) {
+      logger.error`Can't format docs lastUpdatedAt date "${String(date)}"`;
+      throw err;
+    }
+  };
+
   // Assign all of object properties during instantiation (if possible) for
   // NodeJS optimization.
   // Adding properties to object after instantiation will cause hidden
@@ -247,20 +292,23 @@ function doProcessDocMetadata({
   return {
     unversionedId,
     id,
-    isDocsHomePage,
     title,
     description,
     source: aliasedSitePath(filePath, siteDir),
     sourceDirName,
     slug: docSlug,
     permalink,
+    draft,
     editUrl: customEditURL !== undefined ? customEditURL : getDocEditUrl(),
+    tags: normalizeFrontMatterTags(versionMetadata.tagsPath, frontMatter.tags),
     version: versionMetadata.versionName,
     lastUpdatedBy: lastUpdate.lastUpdatedBy,
     lastUpdatedAt: lastUpdate.lastUpdatedAt,
     formattedLastUpdatedAt: lastUpdate.lastUpdatedAt
-      ? new Intl.DateTimeFormat(i18n.currentLocale).format(
-          lastUpdate.lastUpdatedAt * 1000,
+      ? formatDate(
+          i18n.currentLocale,
+          new Date(lastUpdate.lastUpdatedAt * 1000),
+          i18n.localeConfigs[i18n.currentLocale]!.calendar,
         )
       : undefined,
     sidebarPosition,
@@ -273,15 +321,164 @@ export function processDocMetadata(args: {
   versionMetadata: VersionMetadata;
   context: LoadContext;
   options: MetadataOptions;
-}): DocMetadataBase {
+  env: DocEnv;
+}): Promise<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',
+    ): PropNavigationLink | 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'
+>): Parameters<CategoryIndexMatcher>[0] {
+  // 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/frontMatter.ts

@@ -0,0 +1,63 @@
+/**
+ * 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 {
+  JoiFrontMatter as Joi, // Custom instance for front matter
+  URISchema,
+  FrontMatterTagsSchema,
+  FrontMatterTOCHeadingLevels,
+  validateFrontMatter,
+} from '@docusaurus/utils-validation';
+import type {DocFrontMatter} from '@docusaurus/plugin-content-docs';
+
+const FrontMatterLastUpdateErrorMessage =
+  '{{#label}} does not look like a valid front matter FileChange object. Please use a FileChange object (with an author and/or date).';
+
+// NOTE: we don't add any default value on purpose here
+// 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>({
+  id: Joi.string(),
+  // See https://github.com/facebook/docusaurus/issues/4591#issuecomment-822372398
+  title: Joi.string().allow(''),
+  hide_title: Joi.boolean(),
+  hide_table_of_contents: Joi.boolean(),
+  keywords: Joi.array().items(Joi.string().required()),
+  image: URISchema,
+  // See https://github.com/facebook/docusaurus/issues/4591#issuecomment-822372398
+  description: Joi.string().allow(''),
+  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),
+  draft: Joi.boolean(),
+  ...FrontMatterTOCHeadingLevels,
+  last_update: Joi.object({
+    author: Joi.string(),
+    date: Joi.date().raw(),
+  })
+    .or('author', 'date')
+    .messages({
+      'object.missing': FrontMatterLastUpdateErrorMessage,
+      'object.base': FrontMatterLastUpdateErrorMessage,
+    }),
+}).unknown();
+
+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 {getMainDocId} from './docs';
+import type {FullVersion} from './types';
+import type {
+  CategoryGeneratedIndexMetadata,
+  DocMetadata,
+} from '@docusaurus/plugin-content-docs';
+import type {
+  GlobalVersion,
+  GlobalSidebar,
+  GlobalDoc,
+} from '@docusaurus/plugin-content-docs/client';
+import type {Sidebars} from './sidebars/types';
 
-export function toGlobalDataDoc(doc: DocMetadata): GlobalDoc {
+function toGlobalDataDoc(doc: DocMetadata): GlobalDoc {
   return {
     id: doc.unversionedId,
     path: doc.permalink,
@@ -15,13 +27,51 @@ export function toGlobalDataDoc(doc: DocMetadata): GlobalDoc {
   };
 }
 
-export function toGlobalDataVersion(version: LoadedVersion): GlobalVersion {
+function toGlobalDataGeneratedIndex(
+  doc: CategoryGeneratedIndexMetadata,
+): GlobalDoc {
+  return {
+    id: doc.slug,
+    path: doc.permalink,
+    sidebar: doc.sidebar,
+  };
+}
+
+function toGlobalSidebars(
+  sidebars: Sidebars,
+  version: FullVersion,
+): {[sidebarId: string]: GlobalSidebar} {
+  return _.mapValues(sidebars, (sidebar, sidebarId) => {
+    const firstLink = version.sidebarsUtils.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: FullVersion): GlobalVersion {
   return {
     name: version.versionName,
-    label: version.versionLabel,
+    label: version.label,
     isLast: version.isLast,
-    path: version.versionPath,
-    mainDocId: version.mainDocId,
-    docs: version.docs.map(toGlobalDataDoc),
+    path: version.path,
+    mainDocId: getMainDocId(version),
+    docs: version.docs
+      .map(toGlobalDataDoc)
+      .concat(version.categoryGeneratedIndices.map(toGlobalDataGeneratedIndex)),
+    draftIds: version.drafts.map((doc) => doc.unversionedId),
+    sidebars: toGlobalSidebars(version.sidebars, version),
   };
 }