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

package/src/versions/files.ts

@@ -0,0 +1,240 @@
+/**
+ * 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 {
+  getPluginI18nPath,
+  getLocaleConfig,
+  DEFAULT_PLUGIN_ID,
+} from '@docusaurus/utils';
+import {pathExists, readJSON} from '@docusaurus/fs';
+import {
+  VERSIONS_JSON_FILE,
+  VERSIONED_DOCS_DIR,
+  VERSIONED_SIDEBARS_DIR,
+  CURRENT_VERSION_NAME,
+} from '../constants';
+import {validateVersionNames} from './validation';
+import type {
+  PluginOptions,
+  VersionMetadata,
+} from '@docusaurus/plugin-content-docs';
+import type {VersionContext} from './version';
+
+/** Add a prefix like `community_version-1.0.0`. No-op for default instance. */
+function addPluginIdPrefix(fileOrDir: string, pluginId: string): string {
+  return pluginId === DEFAULT_PLUGIN_ID
+    ? fileOrDir
+    : `${pluginId}_${fileOrDir}`;
+}
+
+/** `[siteDir]/community_versioned_docs/version-1.0.0` */
+export function getVersionDocsDirPath(
+  siteDir: string,
+  pluginId: string,
+  versionName: string,
+): string {
+  return path.join(
+    siteDir,
+    addPluginIdPrefix(VERSIONED_DOCS_DIR, pluginId),
+    `version-${versionName}`,
+  );
+}
+
+/** `[siteDir]/community_versioned_sidebars/version-1.0.0-sidebars.json` */
+export function getVersionSidebarsPath(
+  siteDir: string,
+  pluginId: string,
+  versionName: string,
+): string {
+  return path.join(
+    siteDir,
+    addPluginIdPrefix(VERSIONED_SIDEBARS_DIR, pluginId),
+    `version-${versionName}-sidebars.json`,
+  );
+}
+
+export function getDocsDirPathLocalized({
+  localizationDir,
+  pluginId,
+  versionName,
+}: {
+  localizationDir: string;
+  pluginId: string;
+  versionName: string;
+}): string {
+  return getPluginI18nPath({
+    localizationDir,
+    pluginName: 'docusaurus-plugin-content-docs',
+    pluginId,
+    subPaths: [
+      versionName === CURRENT_VERSION_NAME
+        ? CURRENT_VERSION_NAME
+        : `version-${versionName}`,
+    ],
+  });
+}
+
+export function getPluginDirPathLocalized({
+  localizationDir,
+  pluginId,
+}: {
+  localizationDir: string;
+  pluginId: string;
+}): string {
+  return getPluginI18nPath({
+    localizationDir,
+    pluginName: 'docusaurus-plugin-content-docs',
+    pluginId,
+    subPaths: [],
+  });
+}
+
+/** `community` => `[siteDir]/community_versions.json` */
+export function getVersionsFilePath(siteDir: string, pluginId: string): string {
+  return path.join(siteDir, addPluginIdPrefix(VERSIONS_JSON_FILE, pluginId));
+}
+
+/**
+ * Reads the plugin's respective `versions.json` file, and returns its content.
+ *
+ * @throws Throws if validation fails, i.e. `versions.json` doesn't contain an
+ * array of valid version names.
+ */
+export async function readVersionsFile(
+  siteDir: string,
+  pluginId: string,
+): Promise<string[] | null> {
+  const versionsFilePath = getVersionsFilePath(siteDir, pluginId);
+  if (await pathExists(versionsFilePath)) {
+    const content: unknown = await readJSON(versionsFilePath);
+    validateVersionNames(content);
+    return content;
+  }
+  return null;
+}
+
+/**
+ * Reads the `versions.json` file, and returns an ordered list of version names.
+ *
+ * - If `disableVersioning` is turned on, it will return `["current"]` (requires
+ * `includeCurrentVersion` to be true);
+ * - If `includeCurrentVersion` is turned on, "current" will be inserted at the
+ * beginning, if not already there.
+ *
+ * You need to use {@link filterVersions} after this.
+ *
+ * @throws Throws an error if `disableVersioning: true` but `versions.json`
+ * doesn't exist (i.e. site is not versioned)
+ * @throws Throws an error if versions list is empty (empty `versions.json` or
+ * `disableVersioning` is true, and not including current version)
+ */
+export async function readVersionNames(
+  siteDir: string,
+  options: PluginOptions,
+): Promise<string[]> {
+  const versionFileContent = await readVersionsFile(siteDir, options.id);
+
+  if (!versionFileContent && options.disableVersioning) {
+    throw new Error(
+      `Docs: using "disableVersioning: true" option on a non-versioned site does not make sense.`,
+    );
+  }
+
+  const versions = options.disableVersioning ? [] : (versionFileContent ?? []);
+
+  // We add the current version at the beginning, unless:
+  // - user don't want to; or
+  // - it's already been explicitly added to versions.json
+  if (
+    options.includeCurrentVersion &&
+    !versions.includes(CURRENT_VERSION_NAME)
+  ) {
+    versions.unshift(CURRENT_VERSION_NAME);
+  }
+
+  if (versions.length === 0) {
+    throw new Error(
+      `It is not possible to use docs without any version. No version is included because you have requested to not include ${path.resolve(
+        options.path,
+      )} through "includeCurrentVersion: false", while ${
+        options.disableVersioning
+          ? 'versioning is disabled with "disableVersioning: true"'
+          : `the versions file is empty/non-existent`
+      }.`,
+    );
+  }
+
+  return versions;
+}
+
+/**
+ * Gets the path-related version metadata.
+ *
+ * @throws Throws if the resolved docs folder or sidebars file doesn't exist.
+ * Does not throw if a versioned sidebar is missing (since we don't create empty
+ * files).
+ */
+export async function getVersionMetadataPaths({
+  versionName,
+  context,
+  options,
+}: VersionContext): Promise<
+  Pick<
+    VersionMetadata,
+    'contentPath' | 'contentPathLocalized' | 'sidebarFilePath'
+  >
+> {
+  const isCurrent = versionName === CURRENT_VERSION_NAME;
+
+  const shouldTranslate = getLocaleConfig(context.i18n).translate;
+  const contentPathLocalized = shouldTranslate
+    ? getDocsDirPathLocalized({
+        localizationDir: context.localizationDir,
+        pluginId: options.id,
+        versionName,
+      })
+    : undefined;
+
+  const contentPath = isCurrent
+    ? path.resolve(context.siteDir, options.path)
+    : getVersionDocsDirPath(context.siteDir, options.id, versionName);
+  const sidebarFilePath = isCurrent
+    ? options.sidebarPath
+    : getVersionSidebarsPath(context.siteDir, options.id, versionName);
+
+  if (!(await pathExists(contentPath))) {
+    throw new Error(
+      `The docs folder does not exist for version "${versionName}". A docs folder is expected to be found at ${path.relative(
+        context.siteDir,
+        contentPath,
+      )}.`,
+    );
+  }
+
+  // If the current version defines a path to a sidebar file that does not
+  // exist, we throw! Note: for versioned sidebars, the file may not exist (as
+  // we prefer to not create it rather than to create an empty file)
+  // See https://github.com/facebook/docusaurus/issues/3366
+  // See https://github.com/facebook/docusaurus/pull/4775
+  if (
+    versionName === CURRENT_VERSION_NAME &&
+    typeof sidebarFilePath === 'string' &&
+    !(await pathExists(sidebarFilePath))
+  ) {
+    throw new Error(`The path to the sidebar file does not exist at "${path.relative(
+      context.siteDir,
+      sidebarFilePath,
+    )}".
+Please set the docs "sidebarPath" field in your config file to:
+- a sidebars path that exists
+- false: to disable the sidebar
+- undefined: for Docusaurus to generate it automatically`);
+  }
+
+  return {contentPath, contentPathLocalized, sidebarFilePath};
+}

package/src/versions/loadVersion.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 path from 'node:path';
+import _ from 'lodash';
+import {aliasedSitePathToRelativePath, createSlugger} from '@docusaurus/utils';
+import {getTagsFile} from '@docusaurus/utils-validation';
+import logger from '@docusaurus/logger';
+import {
+  addDocNavigation,
+  createDocsByIdIndex,
+  type DocEnv,
+  processDocMetadata,
+  readVersionDocs,
+} from '../docs';
+import {loadSidebars} from '../sidebars';
+import {createSidebarsUtils} from '../sidebars/utils';
+import type {TagsFile} from '@docusaurus/utils';
+import type {
+  DocMetadataBase,
+  LoadedVersion,
+  PluginOptions,
+  VersionMetadata,
+} from '@docusaurus/plugin-content-docs';
+import type {DocFile} from '../types';
+import type {LoadContext} from '@docusaurus/types';
+
+type LoadVersionParams = {
+  context: LoadContext;
+  options: PluginOptions;
+  versionMetadata: VersionMetadata;
+  env: DocEnv;
+};
+
+function ensureNoDuplicateDocId(docs: DocMetadataBase[]): void {
+  const duplicatesById = _.chain(docs)
+    .sort((d1, d2) => {
+      // Need to sort because glob order is non-deterministic
+      // TODO maybe we should create a deterministic glob utils?
+      //  see https://github.com/sindresorhus/globby/issues/131
+      return d1.source.localeCompare(d2.source);
+    })
+    .groupBy((d) => d.id)
+    .pickBy((group) => group.length > 1)
+    .value();
+
+  const duplicateIdEntries = Object.entries(duplicatesById);
+
+  if (duplicateIdEntries.length) {
+    const idMessages = duplicateIdEntries
+      .map(([id, duplicateDocs]) => {
+        return logger.interpolate`- code=${id} found in number=${
+          duplicateDocs.length
+        } docs:
+  - ${duplicateDocs
+    .map((d) => aliasedSitePathToRelativePath(d.source))
+    .join('\n  - ')}`;
+      })
+      .join('\n\n');
+
+    const message = `The docs plugin found docs sharing the same id:
+\n${idMessages}\n
+Docs should have distinct ids.
+In case of conflict, you can rename the docs file, or use the ${logger.code(
+      'id',
+    )} front matter to assign an explicit distinct id to each doc.
+    `;
+
+    throw new Error(message);
+  }
+}
+
+async function loadVersionDocsBase({
+  tagsFile,
+  context,
+  options,
+  versionMetadata,
+  env,
+}: LoadVersionParams & {
+  tagsFile: TagsFile | null;
+}): Promise<DocMetadataBase[]> {
+  const docFiles = await readVersionDocs(versionMetadata, options);
+  if (docFiles.length === 0) {
+    throw new Error(
+      `Docs version "${
+        versionMetadata.versionName
+      }" has no docs! At least one doc should exist at "${path.relative(
+        context.siteDir,
+        versionMetadata.contentPath,
+      )}".`,
+    );
+  }
+  function processVersionDoc(docFile: DocFile) {
+    return processDocMetadata({
+      docFile,
+      versionMetadata,
+      context,
+      options,
+      env,
+      tagsFile,
+    });
+  }
+  const docs = await Promise.all(docFiles.map(processVersionDoc));
+  ensureNoDuplicateDocId(docs);
+  return docs;
+}
+
+async function doLoadVersion({
+  context,
+  options,
+  versionMetadata,
+  env,
+}: LoadVersionParams): Promise<LoadedVersion> {
+  const tagsFile = await getTagsFile({
+    contentPaths: versionMetadata,
+    tags: options.tags,
+  });
+
+  const docsBase: DocMetadataBase[] = await loadVersionDocsBase({
+    tagsFile,
+    context,
+    options,
+    versionMetadata,
+    env,
+  });
+
+  // TODO we only ever need draftIds in further code, not full draft items
+  // To simplify and prevent mistakes, avoid exposing draft
+  // replace draft=>draftIds in content loaded
+  const [drafts, docs] = _.partition(docsBase, (doc) => doc.draft);
+
+  const sidebars = await loadSidebars(versionMetadata.sidebarFilePath, {
+    sidebarItemsGenerator: options.sidebarItemsGenerator,
+    numberPrefixParser: options.numberPrefixParser,
+    docs,
+    drafts,
+    version: versionMetadata,
+    sidebarOptions: {
+      sidebarCollapsed: options.sidebarCollapsed,
+      sidebarCollapsible: options.sidebarCollapsible,
+    },
+    categoryLabelSlugger: createSlugger(),
+  });
+
+  const sidebarsUtils = createSidebarsUtils(sidebars);
+
+  const docsById = createDocsByIdIndex(docs);
+  const allDocIds = Object.keys(docsById);
+
+  sidebarsUtils.checkLegacyVersionedSidebarNames({
+    sidebarFilePath: versionMetadata.sidebarFilePath as string,
+    versionMetadata,
+  });
+  sidebarsUtils.checkSidebarsDocIds({
+    allDocIds,
+    sidebarFilePath: versionMetadata.sidebarFilePath as string,
+    versionMetadata,
+  });
+
+  return {
+    ...versionMetadata,
+    docs: addDocNavigation({
+      docs,
+      sidebarsUtils,
+    }),
+    drafts,
+    sidebars,
+  };
+}
+
+export async function loadVersion(
+  params: LoadVersionParams,
+): Promise<LoadedVersion> {
+  try {
+    return await doLoadVersion(params);
+  } catch (err) {
+    // TODO use error cause (but need to refactor many tests)
+    logger.error`Loading of version failed for version name=${params.versionMetadata.versionName}`;
+    throw err;
+  }
+}

package/src/versions/validation.ts

@@ -0,0 +1,115 @@
+/**
+ * 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 _ from 'lodash';
+import type {VersionsOptions} from '@docusaurus/plugin-content-docs';
+
+export function validateVersionName(name: unknown): asserts name is string {
+  if (typeof name !== 'string') {
+    throw new Error(
+      `Versions should be strings. Found type "${typeof name}" for version ${JSON.stringify(
+        name,
+      )}.`,
+    );
+  }
+  if (!name.trim()) {
+    throw new Error(
+      `Invalid version name "${name}": version name must contain at least one non-whitespace character.`,
+    );
+  }
+  const errors: [RegExp, string][] = [
+    [/[/\\]/, 'should not include slash (/) or backslash (\\)'],
+    [/.{33,}/, 'cannot be longer than 32 characters'],
+    // eslint-disable-next-line no-control-regex
+    [/[<>:"|?*\x00-\x1F]/, 'should be a valid file path'],
+    [/^\.\.?$/, 'should not be "." or ".."'],
+  ];
+
+  errors.forEach(([pattern, message]) => {
+    if (pattern.test(name)) {
+      throw new Error(
+        `Invalid version name "${name}": version name ${message}.`,
+      );
+    }
+  });
+}
+
+export function validateVersionNames(
+  names: unknown,
+): asserts names is string[] {
+  if (!Array.isArray(names)) {
+    throw new Error(
+      `The versions file should contain an array of version names! Found content: ${JSON.stringify(
+        names,
+      )}`,
+    );
+  }
+
+  names.forEach(validateVersionName);
+}
+
+/**
+ * @throws Throws for one of the following invalid options:
+ * - `lastVersion` is non-existent
+ * - `versions` includes unknown keys
+ * - `onlyIncludeVersions` is empty, contains unknown names, or doesn't include
+ * `latestVersion` (if provided)
+ */
+export function validateVersionsOptions(
+  availableVersionNames: string[],
+  options: VersionsOptions,
+): void {
+  const availableVersionNamesMsg = `Available version names are: ${availableVersionNames.join(
+    ', ',
+  )}`;
+  if (
+    options.lastVersion &&
+    !availableVersionNames.includes(options.lastVersion)
+  ) {
+    throw new Error(
+      `Docs option lastVersion: ${options.lastVersion} is invalid. ${availableVersionNamesMsg}`,
+    );
+  }
+  const unknownVersionConfigNames = _.difference(
+    Object.keys(options.versions),
+    availableVersionNames,
+  );
+  if (unknownVersionConfigNames.length > 0) {
+    throw new Error(
+      `Invalid docs option "versions": unknown versions (${unknownVersionConfigNames.join(
+        ',',
+      )}) found. ${availableVersionNamesMsg}`,
+    );
+  }
+
+  if (options.onlyIncludeVersions) {
+    if (options.onlyIncludeVersions.length === 0) {
+      throw new Error(
+        `Invalid docs option "onlyIncludeVersions": an empty array is not allowed, at least one version is needed.`,
+      );
+    }
+    const unknownOnlyIncludeVersionNames = _.difference(
+      options.onlyIncludeVersions,
+      availableVersionNames,
+    );
+    if (unknownOnlyIncludeVersionNames.length > 0) {
+      throw new Error(
+        `Invalid docs option "onlyIncludeVersions": unknown versions (${unknownOnlyIncludeVersionNames.join(
+          ',',
+        )}) found. ${availableVersionNamesMsg}`,
+      );
+    }
+    if (
+      options.lastVersion &&
+      !options.onlyIncludeVersions.includes(options.lastVersion)
+    ) {
+      throw new Error(
+        `Invalid docs option "lastVersion": if you use both the "onlyIncludeVersions" and "lastVersion" options, then "lastVersion" must be present in the provided "onlyIncludeVersions" array.`,
+      );
+    }
+  }
+}