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

package/src/client/structuredDataUtils.ts

@@ -0,0 +1,54 @@
+/**
+ * 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 useDocusaurusContext from '@docusaurus/useDocusaurusContext';
+import {applyTrailingSlash} from '@docusaurus/utils-common';
+import type {PropSidebarBreadcrumbsItem} from '@docusaurus/plugin-content-docs';
+import type {WithContext, BreadcrumbList} from 'schema-dts';
+import type {DocusaurusConfig} from '@docusaurus/types';
+
+type Params = Pick<DocusaurusConfig, 'url' | 'baseUrl' | 'trailingSlash'>;
+
+function getAbsoluteUrl(permalink: string, params: Params): string {
+  const absoluteUrl = `${params.url}${permalink}`;
+  return applyTrailingSlash(absoluteUrl, {
+    trailingSlash: params.trailingSlash,
+    baseUrl: params.baseUrl,
+  });
+}
+
+function getBreadcrumbsStructuredData({
+  breadcrumbs,
+  params,
+}: {
+  breadcrumbs: PropSidebarBreadcrumbsItem[];
+  params: Params;
+}): WithContext<BreadcrumbList> {
+  return {
+    '@context': 'https://schema.org',
+    '@type': 'BreadcrumbList',
+    itemListElement: breadcrumbs
+      // We filter breadcrumb items without links, they are not allowed
+      // See also https://github.com/facebook/docusaurus/issues/9319#issuecomment-2643560845
+      .filter((breadcrumb) => breadcrumb.href)
+      .map((breadcrumb, index) => ({
+        '@type': 'ListItem',
+        position: index + 1,
+        name: breadcrumb.label,
+        item: getAbsoluteUrl(breadcrumb.href!, params),
+      })),
+  };
+}
+
+export function useBreadcrumbsStructuredData({
+  breadcrumbs,
+}: {
+  breadcrumbs: PropSidebarBreadcrumbsItem[];
+}): WithContext<BreadcrumbList> {
+  const {siteConfig} = useDocusaurusContext();
+  return getBreadcrumbsStructuredData({breadcrumbs, params: siteConfig});
+}

package/src/constants.ts

@@ -0,0 +1,15 @@
+/**
+ * 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.
+ */
+
+/** The name of the version that's actively worked on (e.g. `website/docs`) */
+export const CURRENT_VERSION_NAME = 'current';
+/** All doc versions are stored here by version names */
+export const VERSIONED_DOCS_DIR = 'versioned_docs';
+/** All doc versioned sidebars are stored here by version names */
+export const VERSIONED_SIDEBARS_DIR = 'versioned_sidebars';
+/** The version names. Should 1-1 map to the content of versioned docs dir. */
+export const VERSIONS_JSON_FILE = 'versions.json';

package/src/contentHelpers.ts

@@ -0,0 +1,34 @@
+/**
+ * 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 {DocMetadata, LoadedContent} from '@docusaurus/plugin-content-docs';
+
+function indexDocsBySource(content: LoadedContent): Map<string, DocMetadata> {
+  const allDocs = content.loadedVersions.flatMap((v) => v.docs);
+  return new Map(allDocs.map((doc) => [doc.source, doc]));
+}
+
+// TODO this is bad, we should have a better way to do this (new lifecycle?)
+//  The source to doc/permalink is a mutable map passed to the mdx loader
+//  See https://github.com/facebook/docusaurus/pull/10457
+//  See https://github.com/facebook/docusaurus/pull/10185
+export function createContentHelpers() {
+  const sourceToDoc = new Map<string, DocMetadata>();
+  const sourceToPermalink = new Map<string, string>();
+
+  // Mutable map update :/
+  function updateContent(content: LoadedContent): void {
+    sourceToDoc.clear();
+    sourceToPermalink.clear();
+    indexDocsBySource(content).forEach((value, key) => {
+      sourceToDoc.set(key, value);
+      sourceToPermalink.set(key, value.permalink);
+    });
+  }
+
+  return {updateContent, sourceToDoc, sourceToPermalink};
+}

package/src/docs.ts

@@ -0,0 +1,402 @@
+/**
+ * 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 {
+  aliasedSitePath,
+  getEditUrl,
+  getFolderContainingFile,
+  getContentPathList,
+  normalizeUrl,
+  parseMarkdownFile,
+  posixPath,
+  isUnlisted,
+  isDraft,
+  readLastUpdateData,
+  normalizeTags,
+} from '@docusaurus/utils';
+import {glob} from '@docusaurus/glob';
+import {fs} from '@docusaurus/fs';
+import {validateDocFrontMatter} from './frontMatter';
+import getSlug from './slug';
+import {stripPathNumberPrefixes} from './numberPrefix';
+import {toDocNavigationLink, toNavigationLink} from './sidebars/utils';
+import type {TagsFile} from '@docusaurus/utils';
+import type {
+  MetadataOptions,
+  PluginOptions,
+  CategoryIndexMatcher,
+  DocMetadataBase,
+  DocMetadata,
+  PropNavigationLink,
+  VersionMetadata,
+  LoadedVersion,
+} from '@docusaurus/plugin-content-docs';
+import type {LoadContext} from '@docusaurus/types';
+import type {SidebarsUtils} from './sidebars/utils';
+import type {DocFile} from './types';
+
+export async function readDocFile(
+  versionMetadata: Pick<
+    VersionMetadata,
+    'contentPath' | 'contentPathLocalized'
+  >,
+  source: string,
+): Promise<DocFile> {
+  const contentPath = await getFolderContainingFile(
+    getContentPathList(versionMetadata),
+    source,
+  );
+
+  const filePath = path.join(contentPath, source);
+
+  const content = await fs.readFile(filePath, 'utf-8');
+  return {source, content, contentPath, filePath};
+}
+
+export async function readVersionDocs(
+  versionMetadata: VersionMetadata,
+  options: Pick<
+    PluginOptions,
+    'include' | 'exclude' | 'showLastUpdateAuthor' | 'showLastUpdateTime'
+  >,
+): Promise<DocFile[]> {
+  const sources = await glob(options.include, {
+    cwd: versionMetadata.contentPath,
+    ignore: options.exclude,
+  });
+  return Promise.all(
+    sources.map((source) => readDocFile(versionMetadata, source)),
+  );
+}
+
+export type DocEnv = 'production' | 'development';
+
+async function doProcessDocMetadata({
+  docFile,
+  versionMetadata,
+  context,
+  options,
+  env,
+  tagsFile,
+}: {
+  docFile: DocFile;
+  versionMetadata: VersionMetadata;
+  context: LoadContext;
+  options: MetadataOptions;
+  env: DocEnv;
+  tagsFile: TagsFile | null;
+}): Promise<DocMetadataBase> {
+  const {source, content, contentPath, filePath} = docFile;
+  const {
+    siteDir,
+    siteConfig: {
+      markdown: {parseFrontMatter},
+      vcs,
+    },
+  } = context;
+
+  const {
+    frontMatter: unsafeFrontMatter,
+    contentTitle,
+    excerpt,
+  } = await parseMarkdownFile({
+    filePath,
+    fileContent: content,
+    parseFrontMatter,
+  });
+  const frontMatter = validateDocFrontMatter(unsafeFrontMatter);
+
+  const {
+    custom_edit_url: customEditURL,
+
+    // Strip number prefixes by default
+    // (01-MyFolder/01-MyDoc.md => MyFolder/MyDoc)
+    // but allow to disable this behavior with front matter
+    parse_number_prefixes: parseNumberPrefixes = true,
+    last_update: lastUpdateFrontMatter,
+  } = frontMatter;
+
+  const lastUpdate = await readLastUpdateData(
+    filePath,
+    options,
+    lastUpdateFrontMatter,
+    vcs,
+  );
+
+  // E.g. api/plugins/myDoc -> myDoc; myDoc -> myDoc
+  const sourceFileNameWithoutExtension = path.basename(
+    source,
+    path.extname(source),
+  );
+
+  // E.g. api/plugins/myDoc -> api/plugins; myDoc -> .
+  const sourceDirName = path.dirname(source);
+
+  const {filename: unprefixedFileName, numberPrefix} = parseNumberPrefixes
+    ? options.numberPrefixParser(sourceFileNameWithoutExtension)
+    : {filename: sourceFileNameWithoutExtension, numberPrefix: undefined};
+
+  const baseID: string = frontMatter.id ?? unprefixedFileName;
+  if (baseID.includes('/')) {
+    throw new Error(`Document id "${baseID}" cannot include slash.`);
+  }
+
+  // For autogenerated sidebars, sidebar position can come from filename number
+  // prefix or front matter
+  const sidebarPosition: number | undefined =
+    frontMatter.sidebar_position ?? numberPrefix;
+
+  // TODO legacy retrocompatibility
+  // I think it's bad to affect the front matter id with the dirname?
+  function computeDirNameIdPrefix() {
+    if (sourceDirName === '.') {
+      return undefined;
+    }
+    // Eventually remove the number prefixes from intermediate directories
+    return parseNumberPrefixes
+      ? stripPathNumberPrefixes(sourceDirName, options.numberPrefixParser)
+      : sourceDirName;
+  }
+
+  const id = [computeDirNameIdPrefix(), baseID].filter(Boolean).join('/');
+
+  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)
+  const title: string = frontMatter.title ?? contentTitle ?? baseID;
+
+  const description: string = frontMatter.description ?? excerpt ?? '';
+
+  const permalink = normalizeUrl([versionMetadata.path, docSlug]);
+
+  function getDocEditUrl() {
+    const relativeFilePath = path.relative(contentPath, filePath);
+
+    if (typeof options.editUrl === 'function') {
+      return options.editUrl({
+        version: versionMetadata.versionName,
+        versionDocsDirPath: posixPath(
+          path.relative(siteDir, versionMetadata.contentPath),
+        ),
+        docPath: posixPath(relativeFilePath),
+        permalink,
+        locale: context.i18n.currentLocale,
+      });
+    } else if (typeof options.editUrl === 'string') {
+      const isLocalized =
+        typeof versionMetadata.contentPathLocalized !== 'undefined' &&
+        contentPath === versionMetadata.contentPathLocalized;
+      const baseVersionEditUrl =
+        isLocalized && options.editLocalizedFiles
+          ? versionMetadata.editUrlLocalized
+          : versionMetadata.editUrl;
+      return getEditUrl(relativeFilePath, baseVersionEditUrl);
+    }
+    return undefined;
+  }
+
+  const draft = isDraft({env, frontMatter});
+  const unlisted = isUnlisted({env, frontMatter});
+
+  const tags = normalizeTags({
+    options,
+    source,
+    frontMatterTags: frontMatter.tags,
+    tagsBaseRoutePath: versionMetadata.tagsPath,
+    tagsFile,
+  });
+
+  // Assign all of object properties during instantiation (if possible) for
+  // NodeJS optimization.
+  // Adding properties to object after instantiation will cause hidden
+  // class transitions.
+  return {
+    id,
+    title,
+    description,
+    source: aliasedSitePath(filePath, siteDir),
+    sourceDirName,
+    slug: docSlug,
+    permalink,
+    draft,
+    unlisted,
+    editUrl: customEditURL !== undefined ? customEditURL : getDocEditUrl(),
+    tags,
+    version: versionMetadata.versionName,
+    lastUpdatedBy: lastUpdate.lastUpdatedBy,
+    lastUpdatedAt: lastUpdate.lastUpdatedAt,
+    sidebarPosition,
+    frontMatter,
+  };
+}
+
+export async function processDocMetadata(args: {
+  docFile: DocFile;
+  versionMetadata: VersionMetadata;
+  context: LoadContext;
+  options: MetadataOptions;
+  env: DocEnv;
+  tagsFile: TagsFile | null;
+}): Promise<DocMetadataBase> {
+  try {
+    return await doProcessDocMetadata(args);
+  } catch (err) {
+    throw new Error(
+      `Can't process doc metadata for doc at path path=${args.docFile.filePath} in version name=${args.versionMetadata.versionName}`,
+      {cause: err},
+    );
+  }
+}
+
+function getUnlistedIds(docs: DocMetadataBase[]): Set<string> {
+  return new Set(docs.filter((doc) => doc.unlisted).map((doc) => doc.id));
+}
+
+export function addDocNavigation({
+  docs,
+  sidebarsUtils,
+}: {
+  docs: DocMetadataBase[];
+  sidebarsUtils: SidebarsUtils;
+}): LoadedVersion['docs'] {
+  const docsById = createDocsByIdIndex(docs);
+  const unlistedIds = getUnlistedIds(docs);
+
+  // Add sidebar/next/previous to the docs
+  function addNavData(doc: DocMetadataBase): DocMetadata {
+    const navigation = sidebarsUtils.getDocNavigation({
+      docId: doc.id,
+      displayedSidebar: doc.frontMatter.displayed_sidebar,
+      unlistedIds,
+    });
+
+    const toNavigationLinkByDocId = (
+      docId: string | null | undefined,
+      type: 'prev' | 'next',
+    ): PropNavigationLink | 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}.`,
+        );
+      }
+      // Gracefully handle explicitly providing an unlisted doc ID in production
+      if (navDoc.unlisted) {
+        return undefined;
+      }
+      return toDocNavigationLink(navDoc);
+    };
+
+    const previous =
+      doc.frontMatter.pagination_prev !== undefined
+        ? toNavigationLinkByDocId(doc.frontMatter.pagination_prev, 'prev')
+        : toNavigationLink(navigation.previous, docsById);
+    const next =
+      doc.frontMatter.pagination_next !== undefined
+        ? toNavigationLinkByDocId(doc.frontMatter.pagination_next, 'next')
+        : toNavigationLink(navigation.next, docsById);
+
+    return {...doc, sidebar: navigation.sidebarName, previous, next};
+  }
+
+  const docsWithNavigation = docs.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)!;
+    }
+    return docs[0]!;
+  }
+
+  return getMainDoc().id;
+}
+
+// By convention, Docusaurus considers some docs are "indexes":
+// - index.md
+// - readme.md
+// - <folder>/<folder>.md
+//
+// This function is the default implementation of this convention
+//
+// 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 const isCategoryIndex: CategoryIndexMatcher = ({
+  fileName,
+  directories,
+}): boolean => {
+  const eligibleDocIndexNames = [
+    'index',
+    'readme',
+    directories[0]?.toLowerCase(),
+  ];
+  return eligibleDocIndexNames.includes(fileName.toLowerCase());
+};
+
+/**
+ * `guides/sidebar/autogenerated.md` ->
+ *   `'autogenerated', '.md', ['sidebar', 'guides']`
+ */
+export function toCategoryIndexMatcherParam({
+  source,
+  sourceDirName,
+}: Pick<
+  DocMetadataBase,
+  'source' | 'sourceDirName'
+>): Parameters<CategoryIndexMatcher>[0] {
+  // source + sourceDirName are always posix-style
+  return {
+    fileName: path.posix.parse(source).name,
+    extension: path.posix.parse(source).ext,
+    directories: sourceDirName.split(path.posix.sep).reverse(),
+  };
+}
+
+// Docs are indexed by their id
+export function createDocsByIdIndex<Doc extends {id: string}>(
+  docs: Doc[],
+): {[docId: string]: Doc} {
+  return _.keyBy(docs, (d) => d.id);
+}

package/src/frontMatter.ts

@@ -0,0 +1,57 @@
+/**
+ * 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.
+ */
+/* eslint-disable camelcase */
+
+import {
+  JoiFrontMatter as Joi, // Custom instance for front matter
+  URISchema,
+  FrontMatterTagsSchema,
+  FrontMatterTOCHeadingLevels,
+  validateFrontMatter,
+  ContentVisibilitySchema,
+  FrontMatterLastUpdateSchema,
+} from '@docusaurus/utils-validation';
+import type {DocFrontMatter} from '@docusaurus/plugin-content-docs';
+
+// NOTE: we don't add any default value on purpose here
+// 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>({
+  id: Joi.string(),
+  // See https://github.com/facebook/docusaurus/issues/4591#issuecomment-822372398
+  title: Joi.string().allow(''),
+  hide_title: Joi.boolean(),
+  hide_table_of_contents: Joi.boolean(),
+  keywords: Joi.array().items(Joi.string().required()),
+  image: URISchema,
+  // See https://github.com/facebook/docusaurus/issues/4591#issuecomment-822372398
+  description: Joi.string().allow(''),
+  slug: Joi.string(),
+  sidebar_key: Joi.string(),
+  sidebar_label: Joi.string(),
+  sidebar_position: Joi.number(),
+  sidebar_class_name: Joi.string(),
+  sidebar_custom_props: Joi.object().unknown(),
+  displayed_sidebar: Joi.string().allow(null),
+  tags: FrontMatterTagsSchema,
+  pagination_label: Joi.string(),
+  custom_edit_url: URISchema.allow('', null),
+  parse_number_prefixes: Joi.boolean(),
+  pagination_next: Joi.string().allow(null),
+  pagination_prev: Joi.string().allow(null),
+  ...FrontMatterTOCHeadingLevels,
+  last_update: FrontMatterLastUpdateSchema,
+})
+  .unknown()
+  .concat(ContentVisibilitySchema);
+
+export function validateDocFrontMatter(frontMatter: {
+  [key: string]: unknown;
+}): DocFrontMatter {
+  return validateFrontMatter(frontMatter, DocFrontMatterSchema);
+}

package/src/globalData.ts

@@ -0,0 +1,79 @@
+/**
+ * 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 {getMainDocId} from './docs';
+import type {FullVersion} from './types';
+import type {
+  CategoryGeneratedIndexMetadata,
+  DocMetadata,
+} from '@docusaurus/plugin-content-docs';
+import type {
+  GlobalVersion,
+  GlobalSidebar,
+  GlobalDoc,
+} from '@docusaurus/plugin-content-docs/client';
+import type {Sidebars} from './sidebars/types';
+
+function toGlobalDataDoc(doc: DocMetadata): GlobalDoc {
+  return {
+    id: doc.id,
+    path: doc.permalink,
+
+    // optimize global data size: do not add unlisted: false/undefined
+    ...(doc.unlisted && {unlisted: doc.unlisted}),
+
+    // TODO optimize size? remove attribute when no sidebar (breaking change?)
+    sidebar: doc.sidebar,
+  };
+}
+
+function toGlobalDataGeneratedIndex(
+  doc: CategoryGeneratedIndexMetadata,
+): GlobalDoc {
+  return {
+    id: doc.slug,
+    path: doc.permalink,
+    sidebar: doc.sidebar,
+  };
+}
+
+function toGlobalSidebars(
+  sidebars: Sidebars,
+  version: FullVersion,
+): {[sidebarId: string]: GlobalSidebar} {
+  return _.mapValues(sidebars, (sidebar, sidebarId) => {
+    const firstLink = version.sidebarsUtils.getFirstLink(sidebarId);
+    if (!firstLink) {
+      return {};
+    }
+    return {
+      link: {
+        path:
+          firstLink.type === 'generated-index'
+            ? firstLink.permalink
+            : version.docs.find((doc) => doc.id === firstLink.id)!.permalink,
+        label: firstLink.label,
+      },
+    };
+  });
+}
+
+export function toGlobalDataVersion(version: FullVersion): GlobalVersion {
+  return {
+    name: version.versionName,
+    label: version.label,
+    isLast: version.isLast,
+    path: version.path,
+    mainDocId: getMainDocId(version),
+    docs: version.docs
+      .map(toGlobalDataDoc)
+      .concat(version.categoryGeneratedIndices.map(toGlobalDataGeneratedIndex)),
+    draftIds: version.drafts.map((doc) => doc.id),
+    sidebars: toGlobalSidebars(version.sidebars, version),
+  };
+}