@azerion/bunosaurus-plugin-content-docs 0.0.0-stage → 4.0.0

package/src/index.ts

@@ -0,0 +1,289 @@
+/**
+ * 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 path from 'node:path';
+import {
+  normalizeUrl,
+  docuHash,
+  aliasedSitePath,
+  getContentPathList,
+  posixPath,
+  addTrailingPathSeparator,
+  resolveMarkdownLinkPathname,
+  DEFAULT_PLUGIN_ID,
+} from '@docusaurus/utils';
+import {createAbsoluteFilePathMatcher} from '@docusaurus/glob';
+import {getTagsFilePathsToWatch} from '@docusaurus/utils-validation';
+import {createMDXLoaderRule} from '@docusaurus/mdx-loader';
+import {fs} from '@docusaurus/fs';
+import {resolveSidebarPathOption} from './sidebars';
+import {CategoryMetadataFilenamePattern} from './sidebars/generator';
+import {type DocEnv} from './docs';
+import {
+  getVersionFromSourceFilePath,
+  readVersionsMetadata,
+  toFullVersion,
+} from './versions/version';
+import cliDocs from './cli';
+import {VERSIONS_JSON_FILE} from './constants';
+import {toGlobalDataVersion} from './globalData';
+import {
+  translateLoadedContent,
+  getLoadedContentTranslationFiles,
+} from './translations';
+import {createAllRoutes} from './routes';
+
+import {createContentHelpers} from './contentHelpers';
+import {loadVersion} from './versions/loadVersion';
+import type {
+  PluginOptions,
+  VersionMetadata,
+  DocFrontMatter,
+  LoadedContent,
+} from '@docusaurus/plugin-content-docs';
+import type {LoadContext, Plugin} from '@docusaurus/types';
+import type {FullVersion} from './types';
+import type {RuleSetRule} from 'webpack';
+
+// MDX loader is not 100% deterministic, leading to cache invalidation issue
+// This permits to invalidate the MDX loader cache entries when content changes
+// Problem documented here: https://github.com/facebook/docusaurus/pull/10934
+// TODO this is not a perfect solution, find better?
+async function createMdxLoaderDependencyFile({
+  dataDir,
+  options,
+  versionsMetadata,
+}: {
+  dataDir: string;
+  options: PluginOptions;
+  versionsMetadata: VersionMetadata[];
+}): Promise<string | undefined> {
+  // Disabled for unit tests, the side effect produces infinite watch loops
+  // TODO find a better way :/
+  if (process.env.NODE_ENV === 'test') {
+    return undefined;
+  }
+
+  const filePath = path.join(dataDir, '__mdx-loader-dependency.json');
+  // the cache is invalidated whenever this file content changes
+  const fileContent = {
+    options,
+    versionsMetadata,
+  };
+  await fs.mkdir(dataDir, {recursive: true});
+  await fs.writeFile(filePath, JSON.stringify(fileContent));
+  return filePath;
+}
+
+export default async function pluginContentDocs(
+  context: LoadContext,
+  options: PluginOptions,
+): Promise<Plugin<LoadedContent>> {
+  const {siteDir, generatedFilesDir, baseUrl, siteConfig} = context;
+  // Mutate options to resolve sidebar path according to siteDir
+  options.sidebarPath = resolveSidebarPathOption(siteDir, options.sidebarPath);
+
+  const versionsMetadata = await readVersionsMetadata({context, options});
+
+  const pluginId = options.id;
+
+  const pluginDataDirRoot = path.join(
+    generatedFilesDir,
+    'docusaurus-plugin-content-docs',
+  );
+  const dataDir = path.join(pluginDataDirRoot, pluginId);
+  // TODO Docusaurus v4 breaking change
+  //  module aliasing should be automatic
+  //  we should never find local absolute FS paths in the codegen registry
+  const aliasedSource = (source: string) =>
+    `~docs/${posixPath(path.relative(pluginDataDirRoot, source))}`;
+
+  // TODO env should be injected into all plugins
+  const env = process.env.NODE_ENV as DocEnv;
+
+  const contentHelpers = createContentHelpers();
+
+  const mdxLoaderDependency = await createMdxLoaderDependencyFile({
+    dataDir,
+    options,
+    versionsMetadata,
+  });
+
+  function createDocsMDXLoaderRule(): RuleSetRule {
+    const {
+      rehypePlugins,
+      remarkPlugins,
+      recmaPlugins,
+      beforeDefaultRehypePlugins,
+      beforeDefaultRemarkPlugins,
+    } = options;
+    const contentDirs = versionsMetadata
+      .flatMap(getContentPathList)
+      // Trailing slash is important, see https://github.com/facebook/docusaurus/pull/3970
+      .map(addTrailingPathSeparator);
+
+    return createMDXLoaderRule({
+      include: contentDirs,
+      options: {
+        dependencies: [mdxLoaderDependency].filter(
+          (d): d is string => typeof d === 'string',
+        ),
+        admonitions: options.admonitions,
+        remarkPlugins,
+        rehypePlugins,
+        recmaPlugins,
+        beforeDefaultRehypePlugins,
+        beforeDefaultRemarkPlugins,
+        staticDirs: siteConfig.staticDirectories.map((dir) =>
+          path.resolve(siteDir, dir),
+        ),
+        siteDir,
+        isMDXPartial: createAbsoluteFilePathMatcher(
+          options.exclude,
+          contentDirs,
+        ),
+        metadataPath: (mdxPath: string) => {
+          // Note that metadataPath must be the same/in-sync as
+          // the path from createData for each MDX.
+          const aliasedPath = aliasedSitePath(mdxPath, siteDir);
+          return path.join(dataDir, `${docuHash(aliasedPath)}.json`);
+        },
+        // createAssets converts relative paths to require() calls
+        createAssets: ({frontMatter}: {frontMatter: DocFrontMatter}) => ({
+          image: frontMatter.image,
+        }),
+        markdownConfig: siteConfig.markdown,
+        resolveMarkdownLink: ({linkPathname, sourceFilePath}) => {
+          const version = getVersionFromSourceFilePath(
+            sourceFilePath,
+            versionsMetadata,
+          );
+          return resolveMarkdownLinkPathname(linkPathname, {
+            sourceFilePath,
+            sourceToPermalink: contentHelpers.sourceToPermalink,
+            siteDir,
+            contentPaths: version,
+          });
+        },
+      },
+    });
+  }
+
+  const docsMDXLoaderRule = createDocsMDXLoaderRule();
+
+  return {
+    name: 'docusaurus-plugin-content-docs',
+
+    extendCli(cli) {
+      const isDefaultPluginId = pluginId === DEFAULT_PLUGIN_ID;
+
+      // Need to create one distinct command per plugin instance
+      // otherwise 2 instances would try to execute the command!
+      const command = isDefaultPluginId
+        ? 'docs:version'
+        : `docs:version:${pluginId}`;
+      const commandDescription = isDefaultPluginId
+        ? 'Tag a new docs version'
+        : `Tag a new docs version (${pluginId})`;
+
+      cli
+        .command(command)
+        .arguments('<version>')
+        .description(commandDescription)
+        .action((version: unknown) =>
+          cliDocs.cliDocsVersionCommand(version, options, context),
+        );
+    },
+
+    getTranslationFiles({content}) {
+      return getLoadedContentTranslationFiles(content);
+    },
+
+    getPathsToWatch() {
+      function getVersionPathsToWatch(version: VersionMetadata): string[] {
+        const result = [
+          ...options.include.flatMap((pattern) =>
+            getContentPathList(version).map(
+              (docsDirPath) => `${docsDirPath}/${pattern}`,
+            ),
+          ),
+          ...getTagsFilePathsToWatch({
+            contentPaths: version,
+            tags: options.tags,
+          }),
+          `${version.contentPath}/**/${CategoryMetadataFilenamePattern}`,
+        ];
+        if (typeof version.sidebarFilePath === 'string') {
+          result.unshift(version.sidebarFilePath);
+        }
+        return result;
+      }
+
+      return versionsMetadata.flatMap(getVersionPathsToWatch);
+    },
+
+    async loadContent() {
+      return {
+        loadedVersions: await Promise.all(
+          versionsMetadata.map((versionMetadata) =>
+            loadVersion({
+              context,
+              options,
+              env,
+              versionMetadata,
+            }),
+          ),
+        ),
+      };
+    },
+
+    translateContent({content, translationFiles}) {
+      return translateLoadedContent(content, translationFiles);
+    },
+
+    async contentLoaded({content, actions}) {
+      contentHelpers.updateContent(content);
+
+      const versions: FullVersion[] = content.loadedVersions.map(toFullVersion);
+
+      await createAllRoutes({
+        baseUrl,
+        versions,
+        options,
+        actions,
+        aliasedSource,
+      });
+
+      actions.setGlobalData({
+        path: normalizeUrl([baseUrl, options.routeBasePath]),
+        versions: versions.map(toGlobalDataVersion),
+        breadcrumbs: options.breadcrumbs,
+      });
+    },
+
+    configureWebpack() {
+      return {
+        ignoreWarnings: [
+          // Suppress warnings about non-existing of versions file.
+          (e) =>
+            e.message.includes("Can't resolve") &&
+            e.message.includes(VERSIONS_JSON_FILE),
+        ],
+        resolve: {
+          alias: {
+            '~docs': pluginDataDirRoot,
+          },
+        },
+        module: {
+          rules: [docsMDXLoaderRule],
+        },
+      };
+    },
+  };
+}
+
+export {validateOptions} from './options';

package/src/numberPrefix.ts

@@ -0,0 +1,62 @@
+/**
+ * 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 type {NumberPrefixParser} from '@docusaurus/plugin-content-docs';
+
+// Best-effort to avoid parsing some patterns as number prefix
+// 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 (ignoredPrefixPattern.test(filename)) {
+    return {filename, numberPrefix: undefined};
+  }
+  const match = numberPrefixPattern.exec(filename);
+  if (!match) {
+    return {filename, numberPrefix: undefined};
+  }
+  return {
+    filename: match.groups!.suffix!,
+    numberPrefix: parseInt(match.groups!.numberPrefix!, 10),
+  };
+};
+
+export const DisabledNumberPrefixParser: NumberPrefixParser = (
+  filename: string,
+) => ({filename, numberPrefix: undefined});
+
+// 0-myDoc => myDoc
+export function stripNumberPrefix(
+  str: string,
+  parser: NumberPrefixParser,
+): string {
+  return parser(str).filename;
+}
+
+// 0-myFolder/0-mySubfolder/0-myDoc => myFolder/mySubfolder/myDoc
+export function stripPathNumberPrefixes(
+  path: string,
+  parser: NumberPrefixParser,
+): string {
+  return path
+    .split('/')
+    .map((segment) => stripNumberPrefix(segment, parser))
+    .join('/');
+}

package/src/options.ts

@@ -0,0 +1,185 @@
+/**
+ * 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 logger from '@docusaurus/logger';
+import {
+  Joi,
+  RemarkPluginsSchema,
+  RehypePluginsSchema,
+  RecmaPluginsSchema,
+  AdmonitionsSchema,
+  RouteBasePathSchema,
+  URISchema,
+} from '@docusaurus/utils-validation';
+import {GlobExcludeDefault} from '@docusaurus/glob';
+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.
+  tagsBasePath: 'tags', // URL Tags Route.
+  include: ['**/*.{md,mdx}'], // Extensions to include.
+  exclude: GlobExcludeDefault,
+  sidebarItemsGenerator: DefaultSidebarItemsGenerator,
+  numberPrefixParser: DefaultNumberPrefixParser,
+  docsRootComponent: '@theme/DocsRoot',
+  docVersionRootComponent: '@theme/DocVersionRoot',
+  docRootComponent: '@theme/DocRoot',
+  docItemComponent: '@theme/DocItem',
+  docTagDocListComponent: '@theme/DocTagDocListPage',
+  docTagsListComponent: '@theme/DocTagsListPage',
+  docCategoryGeneratedIndexComponent: '@theme/DocCategoryGeneratedIndexPage',
+  remarkPlugins: [],
+  rehypePlugins: [],
+  recmaPlugins: [],
+  beforeDefaultRemarkPlugins: [],
+  beforeDefaultRehypePlugins: [],
+  showLastUpdateTime: false,
+  showLastUpdateAuthor: false,
+  admonitions: true,
+  includeCurrentVersion: true,
+  disableVersioning: false,
+  lastVersion: undefined,
+  versions: {},
+  editCurrentVersion: false,
+  editLocalizedFiles: false,
+  sidebarCollapsible: true,
+  sidebarCollapsed: true,
+  breadcrumbs: true,
+  onInlineTags: 'warn',
+  tags: undefined,
+};
+
+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(),
+  noIndex: Joi.boolean().optional(),
+});
+
+const VersionsOptionsSchema = Joi.object()
+  .pattern(Joi.string().required(), VersionOptionsSchema)
+  .default(DEFAULT_OPTIONS.versions);
+
+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),
+  editLocalizedFiles: Joi.boolean().default(DEFAULT_OPTIONS.editLocalizedFiles),
+  routeBasePath: RouteBasePathSchema.default(DEFAULT_OPTIONS.routeBasePath),
+  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(),
+  ),
+  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: boolean) =>
+          val ? DefaultNumberPrefixParser : DisabledNumberPrefixParser,
+        ),
+      }),
+    )
+    .default(() => DEFAULT_OPTIONS.numberPrefixParser),
+  docsRootComponent: Joi.string().default(DEFAULT_OPTIONS.docsRootComponent),
+  docVersionRootComponent: Joi.string().default(
+    DEFAULT_OPTIONS.docVersionRootComponent,
+  ),
+  docRootComponent: Joi.string().default(DEFAULT_OPTIONS.docRootComponent),
+  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),
+  recmaPlugins: RecmaPluginsSchema.default(DEFAULT_OPTIONS.recmaPlugins),
+  beforeDefaultRemarkPlugins: RemarkPluginsSchema.default(
+    DEFAULT_OPTIONS.beforeDefaultRemarkPlugins,
+  ),
+  beforeDefaultRehypePlugins: RehypePluginsSchema.default(
+    DEFAULT_OPTIONS.beforeDefaultRehypePlugins,
+  ),
+  admonitions: AdmonitionsSchema.default(DEFAULT_OPTIONS.admonitions),
+  showLastUpdateTime: Joi.bool().default(DEFAULT_OPTIONS.showLastUpdateTime),
+  showLastUpdateAuthor: Joi.bool().default(
+    DEFAULT_OPTIONS.showLastUpdateAuthor,
+  ),
+  includeCurrentVersion: Joi.bool().default(
+    DEFAULT_OPTIONS.includeCurrentVersion,
+  ),
+  onlyIncludeVersions: Joi.array().items(Joi.string().required()).optional(),
+  disableVersioning: Joi.bool().default(DEFAULT_OPTIONS.disableVersioning),
+  lastVersion: Joi.string().optional(),
+  versions: VersionsOptionsSchema,
+  breadcrumbs: Joi.bool().default(DEFAULT_OPTIONS.breadcrumbs),
+  onInlineTags: Joi.string()
+    .equal('ignore', 'log', 'warn', 'throw')
+    .default(DEFAULT_OPTIONS.onInlineTags),
+  tags: Joi.string()
+    .disallow('')
+    .allow(null, false)
+    .default(() => DEFAULT_OPTIONS.tags),
+});
+
+export function validateOptions({
+  validate,
+  options: userOptions,
+}: OptionValidationContext<Options, PluginOptions>): PluginOptions {
+  let options = userOptions;
+
+  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);
+
+  return normalizedOptions;
+}