refactor(v2): docs plugin refactor (#3245)

* safe refactorings * safe refactors * add code to read versions more generically * refactor docs plugin * refactors * stable docs refactor * progress on refactor * stable docs refactor * stable docs refactor * stable docs refactor * attempt to fix admonition :( * configureWebpack docs: better typing * more refactors * rename cli * refactor docs metadata processing => move to pure function * stable docs refactor * stable docs refactor * named exports * basic sidebars refactor * add getElementsAround utils * refactor sidebar + ordering/navigation logic * stable retrocompatible refactor * add proper versions metadata tests * fix docs metadata tests * fix docs tests * fix test due to absolute path * fix webpack tests * refactor linkify + add broken markdown links warning * fix DOM warning due to forwarding legacy prop to div element * add todo
2025-06-16 01:32:37 +02:00 · 2020-08-17 17:50:22 +02:00 · 2020-08-17 17:50:22 +02:00 · a4c8a7f55b
commit a4c8a7f55b
parent d17df954b5
54 changed files with 3219 additions and 2724 deletions
--- a/packages/docusaurus-plugin-content-docs/src/options.ts
+++ b/packages/docusaurus-plugin-content-docs/src/options.ts
@ -0,0 +1,103 @@
+/**
+ * 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 * as Joi from '@hapi/joi';
+import {PluginOptions} from './types';
+import {
+  RemarkPluginsSchema,
+  RehypePluginsSchema,
+  AdmonitionsSchema,
+  URISchema,
+} from '@docusaurus/utils-validation';
+import {OptionValidationContext, ValidationResult} from '@docusaurus/types';
+import {ValidationError} from '@hapi/joi';
+import chalk from 'chalk';
+import admonitions from 'remark-admonitions';
+
+export const DEFAULT_OPTIONS: Omit<PluginOptions, 'id'> = {
+  path: 'docs', // Path to data on filesystem, relative to site dir.
+  routeBasePath: 'docs', // URL Route.
+  homePageId: undefined, // TODO remove soon, deprecated
+  include: ['**/*.{md,mdx}'], // Extensions to include.
+  sidebarPath: 'sidebars.json', // Path to sidebar configuration for showing a list of markdown pages.
+  docLayoutComponent: '@theme/DocPage',
+  docItemComponent: '@theme/DocItem',
+  remarkPlugins: [],
+  rehypePlugins: [],
+  showLastUpdateTime: false,
+  showLastUpdateAuthor: false,
+  admonitions: {},
+  excludeNextVersionDocs: false,
+  includeCurrentVersion: true,
+  disableVersioning: false,
+};
+
+export const OptionsSchema = Joi.object({
+  path: Joi.string().default(DEFAULT_OPTIONS.path),
+  editUrl: URISchema,
+  routeBasePath: Joi.string().allow('').default(DEFAULT_OPTIONS.routeBasePath),
+  homePageId: Joi.string().optional(),
+  include: Joi.array().items(Joi.string()).default(DEFAULT_OPTIONS.include),
+  sidebarPath: Joi.string().allow('').default(DEFAULT_OPTIONS.sidebarPath),
+  docLayoutComponent: Joi.string().default(DEFAULT_OPTIONS.docLayoutComponent),
+  docItemComponent: Joi.string().default(DEFAULT_OPTIONS.docItemComponent),
+  remarkPlugins: RemarkPluginsSchema.default(DEFAULT_OPTIONS.remarkPlugins),
+  rehypePlugins: RehypePluginsSchema.default(DEFAULT_OPTIONS.rehypePlugins),
+  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,
+  ),
+  disableVersioning: Joi.bool().default(DEFAULT_OPTIONS.disableVersioning),
+});
+
+// TODO bad validation function types
+export function validateOptions({
+  validate,
+  options,
+}: OptionValidationContext<PluginOptions, ValidationError>): ValidationResult<
+  PluginOptions,
+  ValidationError
+> {
+  // 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: /"`,
+      ),
+    );
+  }
+
+  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;
+  }
+
+  // @ts-expect-error: TODO bad OptionValidationContext, need refactor
+  const normalizedOptions: PluginOptions = validate(OptionsSchema, options);
+
+  if (normalizedOptions.admonitions) {
+    normalizedOptions.remarkPlugins = normalizedOptions.remarkPlugins.concat([
+      [admonitions, normalizedOptions.admonitions],
+    ]);
+  }
+
+  // @ts-expect-error: TODO bad OptionValidationContext, need refactor
+  return normalizedOptions;
+}