@docusaurus/plugin-content-docs 2.0.0-beta.1 → 2.0.0-beta.10

package/src/docFrontMatter.ts

@@ -5,16 +5,17 @@
  * LICENSE file in the root directory of this source tree.
  */
 
-/* eslint-disable camelcase */
-
 import {
   JoiFrontMatter as Joi, // Custom instance for frontmatter
+  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>({
@@ -23,14 +24,19 @@ 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}),
+  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),
+  sidebar_position: Joi.number(),
+  sidebar_class_name: Joi.string(),
+  tags: FrontMatterTagsSchema,
   pagination_label: Joi.string(),
-  custom_edit_url: Joi.string().uri({allowRelative: true}).allow('', null),
+  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,8 @@
 
 import path from 'path';
 import fs from 'fs-extra';
+import chalk from 'chalk';
+import {keyBy, last} from 'lodash';
 import {
   aliasedSitePath,
   getEditUrl,
@@ -14,25 +16,33 @@ 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 {
   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 {
+  SidebarsUtils,
+  toDocNavigationLink,
+  toNavigationLink,
+} from './sidebars/utils';
 
 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 {
@@ -129,8 +139,8 @@ function doProcessDocMetadata({
     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,
+    // but allow to disable this behavior with frontmatter
+    parse_number_prefixes: parseNumberPrefixes = true,
   } = frontMatter;
 
   // ex: api/plugins/myDoc -> myDoc
@@ -144,7 +154,7 @@ function doProcessDocMetadata({
   // 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};
 
@@ -172,7 +182,7 @@ function doProcessDocMetadata({
       return undefined;
     }
     // Eventually remove the number prefixes from intermediate directories
-    return parse_number_prefixes
+    return parseNumberPrefixes
       ? stripPathNumberPrefixes(sourceDirName, options.numberPrefixParser)
       : sourceDirName;
   }
@@ -185,23 +195,14 @@ 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)
@@ -243,7 +244,6 @@ function doProcessDocMetadata({
   return {
     unversionedId,
     id,
-    isDocsHomePage,
     title,
     description,
     source: aliasedSitePath(filePath, siteDir),
@@ -251,6 +251,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,9 +276,137 @@ export function processDocMetadata(args: {
   } catch (e) {
     console.error(
       chalk.red(
-        `Can't process doc metadatas for doc at path "${args.docFile.filePath}" in version "${args.versionMetadata.versionName}"`,
+        `Can't process doc metadata for doc at path "${args.docFile.filePath}" in version "${args.versionMetadata.versionName}"`,
       ),
     );
     throw e;
   }
 }
+
+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,
+    );
+
+    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: DocNavLink | undefined = doc.frontMatter.pagination_prev
+      ? toNavigationLinkByDocId(doc.frontMatter.pagination_prev, 'prev')
+      : toNavigationLink(navigation.previous, docsById);
+    const next: DocNavLink | undefined = doc.frontMatter.pagination_next
+      ? 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)!;
+    } else {
+      return docs[0];
+    }
+  }
+
+  return getMainDoc().unversionedId;
+}
+
+function getLastPathSegment(str: string): string {
+  return last(str.split('/'))!;
+}
+
+// By convention, Docusaurus considers some docs are "indexes":
+// - index.md
+// - readme.md
+// - <folder>/<folder>.md
+//
+// 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 function isConventionalDocIndex(doc: {
+  source: DocMetadataBase['slug'];
+  sourceDirName: DocMetadataBase['sourceDirName'];
+}): boolean {
+  // "@site/docs/folder/subFolder/subSubFolder/myDoc.md" => "myDoc"
+  const docName = path.parse(doc.source).name;
+
+  // "folder/subFolder/subSubFolder" => "subSubFolder"
+  const lastDirName = getLastPathSegment(doc.sourceDirName);
+
+  const eligibleDocIndexNames = ['index', 'readme', lastDirName.toLowerCase()];
+
+  return eligibleDocIndexNames.includes(docName.toLowerCase());
+}
+
+// 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 {
+    ...keyBy(docs, (doc) => doc.unversionedId),
+    ...keyBy(docs, (doc) => doc.id),
+  };
+}

package/src/globalData.ts

@@ -5,7 +5,12 @@
  * LICENSE file in the root directory of this source tree.
  */
 
-import {DocMetadata, GlobalDoc, LoadedVersion, GlobalVersion} from './types';
+import type {
+  DocMetadata,
+  GlobalDoc,
+  LoadedVersion,
+  GlobalVersion,
+} from './types';
 
 export function toGlobalDataDoc(doc: DocMetadata): GlobalDoc {
   return {