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

package/src/markdown/linkify.ts

@@ -5,19 +5,22 @@
  * LICENSE file in the root directory of this source tree.
  */
 
-import {DocsMarkdownOption} from '../types';
-import {getDocsDirPaths} from '../versions';
-import {replaceMarkdownLinks} from '@docusaurus/utils';
+import {replaceMarkdownLinks, getContentPathList} from '@docusaurus/utils';
+import type {DocsMarkdownOption} from '../types';
 
 function getVersion(filePath: string, options: DocsMarkdownOption) {
   const versionFound = options.versionsMetadata.find((version) =>
-    getDocsDirPaths(version).some((docsDirPath) =>
+    getContentPathList(version).some((docsDirPath) =>
       filePath.startsWith(docsDirPath),
     ),
   );
+  // At this point, this should never happen, because the MDX loaders' paths are
+  // literally using the version content paths; but if we allow sourcing content
+  // from outside the docs directory (through the `include` option, for example;
+  // is there a compelling use-case?), this would actually be testable
   if (!versionFound) {
     throw new Error(
-      `Unexpected, markdown file does not belong to any docs version! file=${filePath}`,
+      `Unexpected error: Markdown file at "${filePath}" does not belong to any docs version!`,
     );
   }
   return versionFound;

package/src/numberPrefix.ts

@@ -5,43 +5,36 @@
  * LICENSE file in the root directory of this source tree.
  */
 
-import {NumberPrefixParser} from './types';
+import type {NumberPrefixParser} from '@docusaurus/plugin-content-docs';
 
 // Best-effort to avoid parsing some patterns as number prefix
-const IgnoredPrefixPatterns = (function () {
-  // ignore common date-like patterns: https://github.com/facebook/docusaurus/issues/4640
-  const DateLikePrefixRegex = /^((\d{2}|\d{4})[-_.]\d{2}([-_.](\d{2}|\d{4}))?)(.*)$/;
-
-  // ignore common versioning patterns: https://github.com/facebook/docusaurus/issues/4653
-  // note: we could try to parse float numbers in filenames but that is probably not worth it
-  // as a version such as "8.0" can be interpreted as both a version and a float
-  // User can configure his own NumberPrefixParser if he wants 8.0 to be interpreted as a float
-  const VersionLikePrefixRegex = /^(\d+[-_.]\d+)(.*)$/;
-
-  return new RegExp(
-    `${DateLikePrefixRegex.source}|${VersionLikePrefixRegex.source}`,
-  );
-})();
-
-const NumberPrefixRegex = /^(?<numberPrefix>\d+)(?<separator>\s*[-_.]+\s*)(?<suffix>.*)$/;
+// ignore common date-like patterns: https://github.com/facebook/docusaurus/issues/4640
+// ignore common versioning patterns: https://github.com/facebook/docusaurus/issues/4653
+// Both of them would look like 7.0-foo or 2021-11-foo
+// note: we could try to parse float numbers in filenames, but that is probably
+// not worth it, as a version such as "8.0" can be interpreted as either a
+// version or a float. User can configure her own NumberPrefixParser if she
+// wants 8.0 to be interpreted as a float
+const ignoredPrefixPattern = /^\d+[-_.]\d+/;
+
+const numberPrefixPattern =
+  /^(?<numberPrefix>\d+)\s*[-_.]+\s*(?<suffix>[^-_.\s].*)$/;
 
 // 0-myDoc => {filename: myDoc, numberPrefix: 0}
 // 003 - myDoc => {filename: myDoc, numberPrefix: 3}
 export const DefaultNumberPrefixParser: NumberPrefixParser = (
   filename: string,
 ) => {
-  if (IgnoredPrefixPatterns.exec(filename)) {
+  if (ignoredPrefixPattern.test(filename)) {
+    return {filename, numberPrefix: undefined};
+  }
+  const match = numberPrefixPattern.exec(filename);
+  if (!match) {
     return {filename, numberPrefix: undefined};
   }
-  const match = NumberPrefixRegex.exec(filename);
-  const cleanFileName = match?.groups?.suffix ?? filename;
-  const numberPrefixString = match?.groups?.numberPrefix;
-  const numberPrefix = numberPrefixString
-    ? parseInt(numberPrefixString, 10)
-    : undefined;
   return {
-    filename: cleanFileName,
-    numberPrefix,
+    filename: match.groups!.suffix!,
+    numberPrefix: parseInt(match.groups!.numberPrefix!, 10),
   };
 };
 

package/src/options.ts

@@ -4,7 +4,8 @@
  * This source code is licensed under the MIT license found in the
  * LICENSE file in the root directory of this source tree.
  */
-import {PluginOptions} from './types';
+
+import logger from '@docusaurus/logger';
 import {
   Joi,
   RemarkPluginsSchema,
@@ -12,50 +13,59 @@ import {
   AdmonitionsSchema,
   URISchema,
 } from '@docusaurus/utils-validation';
-import {OptionValidationContext, ValidationResult} from '@docusaurus/types';
-import chalk from 'chalk';
-import admonitions from 'remark-admonitions';
-import {DefaultSidebarItemsGenerator} from './sidebarItemsGenerator';
+import {GlobExcludeDefault} from '@docusaurus/utils';
+import {DefaultSidebarItemsGenerator} from './sidebars/generator';
 import {
   DefaultNumberPrefixParser,
   DisabledNumberPrefixParser,
 } from './numberPrefix';
+import type {OptionValidationContext} from '@docusaurus/types';
+import type {PluginOptions, Options} from '@docusaurus/plugin-content-docs';
 
 export const DEFAULT_OPTIONS: Omit<PluginOptions, 'id' | 'sidebarPath'> = {
   path: 'docs', // Path to data on filesystem, relative to site dir.
   routeBasePath: 'docs', // URL Route.
-  homePageId: undefined, // TODO remove soon, deprecated
+  tagsBasePath: 'tags', // URL Tags Route.
   include: ['**/*.{md,mdx}'], // Extensions to include.
+  exclude: GlobExcludeDefault,
   sidebarItemsGenerator: DefaultSidebarItemsGenerator,
   numberPrefixParser: DefaultNumberPrefixParser,
   docLayoutComponent: '@theme/DocPage',
   docItemComponent: '@theme/DocItem',
+  docTagDocListComponent: '@theme/DocTagDocListPage',
+  docTagsListComponent: '@theme/DocTagsListPage',
+  docCategoryGeneratedIndexComponent: '@theme/DocCategoryGeneratedIndexPage',
   remarkPlugins: [],
   rehypePlugins: [],
   beforeDefaultRemarkPlugins: [],
   beforeDefaultRehypePlugins: [],
   showLastUpdateTime: false,
   showLastUpdateAuthor: false,
-  admonitions: {},
-  excludeNextVersionDocs: false,
+  admonitions: true,
   includeCurrentVersion: true,
   disableVersioning: false,
   lastVersion: undefined,
   versions: {},
   editCurrentVersion: false,
   editLocalizedFiles: false,
+  sidebarCollapsible: true,
+  sidebarCollapsed: true,
+  breadcrumbs: true,
 };
 
 const VersionOptionsSchema = Joi.object({
   path: Joi.string().allow('').optional(),
   label: Joi.string().optional(),
+  banner: Joi.string().equal('none', 'unreleased', 'unmaintained').optional(),
+  badge: Joi.boolean().optional(),
+  className: Joi.string().optional(),
 });
 
 const VersionsOptionsSchema = Joi.object()
   .pattern(Joi.string().required(), VersionOptionsSchema)
   .default(DEFAULT_OPTIONS.versions);
 
-export const OptionsSchema = Joi.object({
+const OptionsSchema = Joi.object<PluginOptions>({
   path: Joi.string().default(DEFAULT_OPTIONS.path),
   editUrl: Joi.alternatives().try(URISchema, Joi.function()),
   editCurrentVersion: Joi.boolean().default(DEFAULT_OPTIONS.editCurrentVersion),
@@ -64,8 +74,15 @@ export const OptionsSchema = Joi.object({
     // '' not allowed, see https://github.com/facebook/docusaurus/issues/3374
     // .allow('') ""
     .default(DEFAULT_OPTIONS.routeBasePath),
-  homePageId: Joi.string().optional(),
+  tagsBasePath: Joi.string().default(DEFAULT_OPTIONS.tagsBasePath),
+  // @ts-expect-error: deprecated
+  homePageId: Joi.any().forbidden().messages({
+    'any.unknown':
+      'The docs plugin option homePageId is not supported anymore. To make a doc the "home", please add "slug: /" in its front matter. See: https://docusaurus.io/docs/next/docs-introduction#home-page-docs',
+  }),
+
   include: Joi.array().items(Joi.string()).default(DEFAULT_OPTIONS.include),
+  exclude: Joi.array().items(Joi.string()).default(DEFAULT_OPTIONS.exclude),
   sidebarPath: Joi.alternatives().try(
     Joi.boolean().invalid(true),
     Joi.string(),
@@ -73,12 +90,14 @@ export const OptionsSchema = Joi.object({
   sidebarItemsGenerator: Joi.function().default(
     () => DEFAULT_OPTIONS.sidebarItemsGenerator,
   ),
+  sidebarCollapsible: Joi.boolean().default(DEFAULT_OPTIONS.sidebarCollapsible),
+  sidebarCollapsed: Joi.boolean().default(DEFAULT_OPTIONS.sidebarCollapsed),
   numberPrefixParser: Joi.alternatives()
     .try(
       Joi.function(),
       // Convert boolean values to functions
       Joi.alternatives().conditional(Joi.boolean(), {
-        then: Joi.custom((val) =>
+        then: Joi.custom((val: boolean) =>
           val ? DefaultNumberPrefixParser : DisabledNumberPrefixParser,
         ),
       }),
@@ -86,6 +105,15 @@ export const OptionsSchema = Joi.object({
     .default(() => DEFAULT_OPTIONS.numberPrefixParser),
   docLayoutComponent: Joi.string().default(DEFAULT_OPTIONS.docLayoutComponent),
   docItemComponent: Joi.string().default(DEFAULT_OPTIONS.docItemComponent),
+  docTagsListComponent: Joi.string().default(
+    DEFAULT_OPTIONS.docTagsListComponent,
+  ),
+  docTagDocListComponent: Joi.string().default(
+    DEFAULT_OPTIONS.docTagDocListComponent,
+  ),
+  docCategoryGeneratedIndexComponent: Joi.string().default(
+    DEFAULT_OPTIONS.docCategoryGeneratedIndexComponent,
+  ),
   remarkPlugins: RemarkPluginsSchema.default(DEFAULT_OPTIONS.remarkPlugins),
   rehypePlugins: RehypePluginsSchema.default(DEFAULT_OPTIONS.rehypePlugins),
   beforeDefaultRemarkPlugins: RemarkPluginsSchema.default(
@@ -94,16 +122,11 @@ export const OptionsSchema = Joi.object({
   beforeDefaultRehypePlugins: RehypePluginsSchema.default(
     DEFAULT_OPTIONS.beforeDefaultRehypePlugins,
   ),
-  admonitions: Joi.alternatives()
-    .try(AdmonitionsSchema, Joi.boolean().invalid(true))
-    .default(DEFAULT_OPTIONS.admonitions),
+  admonitions: AdmonitionsSchema.default(DEFAULT_OPTIONS.admonitions),
   showLastUpdateTime: Joi.bool().default(DEFAULT_OPTIONS.showLastUpdateTime),
   showLastUpdateAuthor: Joi.bool().default(
     DEFAULT_OPTIONS.showLastUpdateAuthor,
   ),
-  excludeNextVersionDocs: Joi.bool().default(
-    DEFAULT_OPTIONS.excludeNextVersionDocs,
-  ),
   includeCurrentVersion: Joi.bool().default(
     DEFAULT_OPTIONS.includeCurrentVersion,
   ),
@@ -111,40 +134,35 @@ export const OptionsSchema = Joi.object({
   disableVersioning: Joi.bool().default(DEFAULT_OPTIONS.disableVersioning),
   lastVersion: Joi.string().optional(),
   versions: VersionsOptionsSchema,
+  breadcrumbs: Joi.bool().default(DEFAULT_OPTIONS.breadcrumbs),
 });
 
 export function validateOptions({
   validate,
-  options,
-}: OptionValidationContext<PluginOptions>): ValidationResult<PluginOptions> {
-  // TODO remove homePageId before end of 2020
-  // "slug: /" is better because the home doc can be different across versions
-  if (options.homePageId) {
-    console.log(
-      chalk.red(
-        `The docs plugin option homePageId=${options.homePageId} is deprecated. To make a doc the "home", prefer frontmatter: "slug: /"`,
-      ),
-    );
-  }
+  options: userOptions,
+}: OptionValidationContext<Options, PluginOptions>): PluginOptions {
+  let options = userOptions;
 
-  if (typeof options.excludeNextVersionDocs !== 'undefined') {
-    console.log(
-      chalk.red(
-        `The docs plugin option excludeNextVersionDocs=${
-          options.excludeNextVersionDocs
-        } is deprecated. Use the includeCurrentVersion=${!options.excludeNextVersionDocs} option instead!"`,
-      ),
-    );
-    options.includeCurrentVersion = !options.excludeNextVersionDocs;
+  if (options.sidebarCollapsible === false) {
+    // When sidebarCollapsible=false and sidebarCollapsed=undefined, we don't
+    // want to have the inconsistency warning. We let options.sidebarCollapsible
+    // become the default value for options.sidebarCollapsed
+    if (typeof options.sidebarCollapsed === 'undefined') {
+      options = {
+        ...options,
+        sidebarCollapsed: false,
+      };
+    }
+    if (options.sidebarCollapsed) {
+      logger.warn`The docs plugin config is inconsistent. It does not make sense to use code=${'sidebarCollapsible: false'} and code=${'sidebarCollapsed: true'} at the same time. code=${'sidebarCollapsed: true'} will be ignored.`;
+      options = {
+        ...options,
+        sidebarCollapsed: false,
+      };
+    }
   }
 
   const normalizedOptions = validate(OptionsSchema, options);
 
-  if (normalizedOptions.admonitions) {
-    normalizedOptions.remarkPlugins = normalizedOptions.remarkPlugins.concat([
-      [admonitions, normalizedOptions.admonitions],
-    ]);
-  }
-
   return normalizedOptions;
 }