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

package/src/props.ts

@@ -0,0 +1,223 @@
+/**
+ * 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 {createDocsByIdIndex} from './docs';
+import type {VersionTag, VersionTags} from './types';
+import type {
+  SidebarItemDoc,
+  SidebarItem,
+  SidebarItemCategory,
+  SidebarItemCategoryLink,
+} from './sidebars/types';
+import type {
+  PropSidebars,
+  PropVersionMetadata,
+  PropSidebarItem,
+  PropSidebarItemCategory,
+  PropTagDocList,
+  PropTagDocListDoc,
+  PropTagsListPage,
+  PropSidebarItemLink,
+  PropVersionDocs,
+  DocMetadata,
+  LoadedVersion,
+} from '@docusaurus/plugin-content-docs';
+
+export function toSidebarDocItemLinkProp({
+  item,
+  doc,
+}: {
+  item: SidebarItemDoc;
+  doc: Pick<
+    DocMetadata,
+    'id' | 'title' | 'permalink' | 'unlisted' | 'frontMatter'
+  >;
+}): PropSidebarItemLink {
+  const {id, title, permalink, frontMatter, unlisted} = doc;
+  return {
+    type: 'link',
+    ...(item.key && {key: item.key}),
+    href: permalink,
+    // Front Matter data takes precedence over sidebars.json
+    label: frontMatter.sidebar_label ?? item.label ?? title,
+    className: frontMatter.sidebar_class_name ?? item.className,
+    customProps: frontMatter.sidebar_custom_props ?? item.customProps,
+    docId: id,
+    unlisted,
+  };
+}
+
+export function toSidebarsProp(
+  loadedVersion: Pick<LoadedVersion, 'docs' | 'sidebars'>,
+): PropSidebars {
+  const docsById = createDocsByIdIndex(loadedVersion.docs);
+
+  function getDocById(docId: string): DocMetadata {
+    const docMetadata = docsById[docId];
+    if (!docMetadata) {
+      throw new Error(
+        `Invalid sidebars file. The document with id "${docId}" was used in the sidebar, but no document with this id could be found.
+Available document ids are:
+- ${Object.keys(docsById).sort().join('\n- ')}`,
+      );
+    }
+    return docMetadata;
+  }
+
+  const convertDocLink = (item: SidebarItemDoc): PropSidebarItemLink => {
+    const doc = getDocById(item.id);
+    return toSidebarDocItemLinkProp({item, doc});
+  };
+
+  function getCategoryLinkHref(
+    link: SidebarItemCategoryLink | undefined,
+  ): string | undefined {
+    switch (link?.type) {
+      case 'doc':
+        return getDocById(link.id).permalink;
+      case 'generated-index':
+        return link.permalink;
+      default:
+        return undefined;
+    }
+  }
+
+  function getCategoryLinkUnlisted(
+    link: SidebarItemCategoryLink | undefined,
+  ): boolean {
+    if (link?.type === 'doc') {
+      return getDocById(link.id).unlisted;
+    }
+    return false;
+  }
+
+  function getCategoryLinkCustomProps(
+    link: SidebarItemCategoryLink | undefined,
+  ) {
+    switch (link?.type) {
+      case 'doc':
+        return getDocById(link.id).frontMatter.sidebar_custom_props;
+      default:
+        return undefined;
+    }
+  }
+
+  function convertCategory(item: SidebarItemCategory): PropSidebarItemCategory {
+    const {link, ...rest} = item;
+    const href = getCategoryLinkHref(link);
+    const linkUnlisted = getCategoryLinkUnlisted(link);
+    const customProps = item.customProps ?? getCategoryLinkCustomProps(link);
+
+    return {
+      ...rest,
+      items: item.items.map(normalizeItem),
+      ...(href && {href}),
+      ...(linkUnlisted && {linkUnlisted}),
+      ...(customProps && {customProps}),
+    };
+  }
+
+  function normalizeItem(item: SidebarItem): PropSidebarItem {
+    switch (item.type) {
+      case 'category':
+        return convertCategory(item);
+      case 'ref':
+      case 'doc':
+        return convertDocLink(item);
+      case 'link':
+      default:
+        return item;
+    }
+  }
+
+  // Transform the sidebar so that all sidebar item will be in the
+  // form of 'link' or 'category' only.
+  // This is what will be passed as props to the UI component.
+  return _.mapValues(loadedVersion.sidebars, (items) =>
+    items.map(normalizeItem),
+  );
+}
+
+function toVersionDocsProp(loadedVersion: LoadedVersion): PropVersionDocs {
+  return Object.fromEntries(
+    loadedVersion.docs.map((doc) => [
+      doc.id,
+      {
+        id: doc.id,
+        title: doc.title,
+        description: doc.description,
+        sidebar: doc.sidebar,
+      },
+    ]),
+  );
+}
+
+export function toVersionMetadataProp(
+  pluginId: string,
+  loadedVersion: LoadedVersion,
+): PropVersionMetadata {
+  return {
+    pluginId,
+    version: loadedVersion.versionName,
+    label: loadedVersion.label,
+    banner: loadedVersion.banner,
+    badge: loadedVersion.badge,
+    noIndex: loadedVersion.noIndex,
+    className: loadedVersion.className,
+    isLast: loadedVersion.isLast,
+    docsSidebars: toSidebarsProp(loadedVersion),
+    docs: toVersionDocsProp(loadedVersion),
+  };
+}
+
+export function toTagDocListProp({
+  allTagsPath,
+  tag,
+  docs,
+}: {
+  allTagsPath: string;
+  tag: VersionTag;
+  docs: DocMetadata[];
+}): PropTagDocList {
+  function toDocListProp(): PropTagDocListDoc[] {
+    const list = _.compact(
+      tag.docIds.map((id) => docs.find((doc) => doc.id === id)),
+    );
+    // Sort docs by title
+    list.sort((doc1, doc2) => doc1.title.localeCompare(doc2.title));
+    return list.map((doc) => ({
+      id: doc.id,
+      title: doc.title,
+      description: doc.description,
+      permalink: doc.permalink,
+    }));
+  }
+
+  return {
+    label: tag.label,
+    permalink: tag.permalink,
+    description: tag.description,
+    allTagsPath,
+    count: tag.docIds.length,
+    items: toDocListProp(),
+    unlisted: tag.unlisted,
+  };
+}
+
+export function toTagsListTagsProp(
+  versionTags: VersionTags,
+): PropTagsListPage['tags'] {
+  return Object.values(versionTags)
+    .filter((tagValue) => !tagValue.unlisted)
+    .map((tagValue) => ({
+      label: tagValue.label,
+      permalink: tagValue.permalink,
+      description: tagValue.description,
+      count: tagValue.docIds.length,
+    }));
+}

package/src/routes.ts

@@ -0,0 +1,263 @@
+/**
+ * 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 logger from '@docusaurus/logger';
+import {
+  docuHash,
+  normalizeUrl,
+  aliasedSitePathToRelativePath,
+  groupTaggedItems,
+  getTagVisibility,
+} from '@docusaurus/utils';
+import {
+  toTagDocListProp,
+  toTagsListTagsProp,
+  toVersionMetadataProp,
+} from './props';
+import type {
+  PluginContentLoadedActions,
+  RouteConfig,
+  RouteMetadata,
+} from '@docusaurus/types';
+import type {FullVersion, VersionTag, VersionTags} from './types';
+import type {
+  CategoryGeneratedIndexMetadata,
+  DocMetadata,
+  PluginOptions,
+} from '@docusaurus/plugin-content-docs';
+
+function createDocRouteMetadata(docMeta: DocMetadata): RouteMetadata {
+  return {
+    sourceFilePath: aliasedSitePathToRelativePath(docMeta.source),
+    lastUpdatedAt: docMeta.lastUpdatedAt,
+  };
+}
+
+async function buildVersionCategoryGeneratedIndexRoutes({
+  version,
+  options,
+}: BuildVersionRoutesParam): Promise<RouteConfig[]> {
+  async function buildCategoryGeneratedIndexRoute(
+    categoryGeneratedIndex: CategoryGeneratedIndexMetadata,
+  ): Promise<RouteConfig> {
+    return {
+      path: categoryGeneratedIndex.permalink,
+      component: options.docCategoryGeneratedIndexComponent,
+      exact: true,
+      props: {
+        categoryGeneratedIndex,
+      },
+      // Same as doc, this sidebar route attribute permits to associate this
+      // subpage to the given sidebar
+      ...(categoryGeneratedIndex.sidebar && {
+        sidebar: categoryGeneratedIndex.sidebar,
+      }),
+    };
+  }
+
+  return Promise.all(
+    version.categoryGeneratedIndices.map(buildCategoryGeneratedIndexRoute),
+  );
+}
+
+async function buildVersionDocRoutes({
+  version,
+  actions,
+  options,
+}: BuildVersionRoutesParam): Promise<RouteConfig[]> {
+  return Promise.all(
+    version.docs.map(async (doc) => {
+      await actions.createData(
+        // Note that this created data path must be in sync with
+        // metadataPath provided to mdx-loader.
+        `${docuHash(doc.source)}.json`,
+        doc,
+      );
+
+      const docRoute: RouteConfig = {
+        path: doc.permalink,
+        component: options.docItemComponent,
+        exact: true,
+        modules: {
+          content: doc.source,
+        },
+        metadata: createDocRouteMetadata(doc),
+        // Because the parent (DocRoot) comp need to access it easily
+        // This permits to render the sidebar once without unmount/remount when
+        // navigating (and preserve sidebar state)
+        ...(doc.sidebar && {
+          sidebar: doc.sidebar,
+        }),
+      };
+
+      return docRoute;
+    }),
+  );
+}
+
+async function buildVersionSidebarRoute(param: BuildVersionRoutesParam) {
+  const [docRoutes, categoryGeneratedIndexRoutes] = await Promise.all([
+    buildVersionDocRoutes(param),
+    buildVersionCategoryGeneratedIndexRoutes(param),
+  ]);
+  const subRoutes = [...docRoutes, ...categoryGeneratedIndexRoutes];
+  return {
+    path: param.version.path,
+    exact: false,
+    component: param.options.docRootComponent,
+    routes: subRoutes,
+  };
+}
+function getVersionTags(docs: DocMetadata[]): VersionTags {
+  const groups = groupTaggedItems(docs, (doc) => doc.tags);
+  return _.mapValues(groups, ({tag, items: tagDocs}) => {
+    const tagVisibility = getTagVisibility({
+      items: tagDocs,
+      isUnlisted: (item) => item.unlisted,
+    });
+    return {
+      inline: tag.inline,
+      label: tag.label,
+      permalink: tag.permalink,
+      description: tag.description,
+      docIds: tagVisibility.listedItems.map((item) => item.id),
+      unlisted: tagVisibility.unlisted,
+    };
+  });
+}
+
+async function buildVersionTagsRoutes(
+  param: BuildVersionRoutesParam,
+): Promise<RouteConfig[]> {
+  const {version, options} = param;
+  const versionTags = getVersionTags(version.docs);
+
+  async function buildTagsListRoute(): Promise<RouteConfig | null> {
+    const tags = toTagsListTagsProp(versionTags);
+    // Don't create a tags list page if there's no tag
+    if (tags.length === 0) {
+      return null;
+    }
+    return {
+      path: version.tagsPath,
+      exact: true,
+      component: options.docTagsListComponent,
+      props: {
+        tags,
+      },
+    };
+  }
+
+  async function buildTagDocListRoute(tag: VersionTag): Promise<RouteConfig> {
+    return {
+      path: tag.permalink,
+      component: options.docTagDocListComponent,
+      exact: true,
+      props: {
+        tag: toTagDocListProp({
+          allTagsPath: version.tagsPath,
+          tag,
+          docs: version.docs,
+        }),
+      },
+    };
+  }
+
+  const [tagsListRoute, allTagsDocListRoutes] = await Promise.all([
+    buildTagsListRoute(),
+    Promise.all(Object.values(versionTags).map(buildTagDocListRoute)),
+  ]);
+
+  return _.compact([tagsListRoute, ...allTagsDocListRoutes]);
+}
+
+type BuildVersionRoutesParam = Omit<BuildAllRoutesParam, 'versions'> & {
+  version: FullVersion;
+};
+
+async function buildVersionRoutes(
+  param: BuildVersionRoutesParam,
+): Promise<RouteConfig> {
+  const {version, options} = param;
+
+  async function buildVersionSubRoutes() {
+    const [sidebarRoute, tagsRoutes] = await Promise.all([
+      buildVersionSidebarRoute(param),
+      buildVersionTagsRoutes(param),
+    ]);
+
+    return [sidebarRoute, ...tagsRoutes];
+  }
+
+  async function doBuildVersionRoutes(): Promise<RouteConfig> {
+    return {
+      path: version.path,
+      exact: false,
+      component: options.docVersionRootComponent,
+      routes: await buildVersionSubRoutes(),
+      props: {
+        // TODO Docusaurus v4 breaking change?
+        //  expose version metadata as route context instead of props
+        version: toVersionMetadataProp(options.id, version),
+      },
+      priority: version.routePriority,
+    };
+  }
+
+  try {
+    return await doBuildVersionRoutes();
+  } catch (err) {
+    logger.error`Can't create version routes for version name=${version.versionName}`;
+    throw err;
+  }
+}
+
+type BuildAllRoutesParam = Omit<CreateAllRoutesParam, 'actions'> & {
+  actions: Omit<PluginContentLoadedActions, 'addRoute' | 'setGlobalData'>;
+};
+
+// TODO we want this buildAllRoutes function to be easily testable
+// Ideally, we should avoid side effects here (ie not injecting actions)
+export async function buildAllRoutes(
+  param: BuildAllRoutesParam,
+): Promise<RouteConfig[]> {
+  const subRoutes = await Promise.all(
+    param.versions.map((version) =>
+      buildVersionRoutes({
+        ...param,
+        version,
+      }),
+    ),
+  );
+
+  // all docs routes are wrapped under a single parent route, this ensures
+  // the theme layout never unmounts/remounts when navigating between versions
+  return [
+    {
+      path: normalizeUrl([param.baseUrl, param.options.routeBasePath]),
+      exact: false,
+      component: param.options.docsRootComponent,
+      routes: subRoutes,
+    },
+  ];
+}
+
+type CreateAllRoutesParam = {
+  baseUrl: string;
+  versions: FullVersion[];
+  options: PluginOptions;
+  actions: PluginContentLoadedActions;
+  aliasedSource: (str: string) => string;
+};
+
+export async function createAllRoutes(
+  param: CreateAllRoutesParam,
+): Promise<void> {
+  const routes = await buildAllRoutes(param);
+  routes.forEach(param.actions.addRoute);
+}

package/src/server-export.ts

@@ -0,0 +1,26 @@
+/**
+ * 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.
+ */
+
+// APIs available to Node.js
+// Those are undocumented but used by some third-party plugins
+// For this reason it's preferable to avoid doing breaking changes
+// See also https://github.com/facebook/docusaurus/pull/6477
+
+export {
+  CURRENT_VERSION_NAME,
+  VERSIONED_DOCS_DIR,
+  VERSIONED_SIDEBARS_DIR,
+  VERSIONS_JSON_FILE,
+} from './constants';
+
+export {
+  filterVersions,
+  getDefaultVersionBanner,
+  getVersionBadge,
+  getVersionBanner,
+} from './versions/version';
+export {readVersionNames} from './versions/files';

package/src/sidebars/README.md

@@ -0,0 +1,10 @@
+# Sidebars
+
+This part is very complicated and hard to navigate. Sidebars are loaded through the following steps:
+
+1. **Loading**. The sidebars file is read. Returns `SidebarsConfig`.
+2. **Normalization**. The shorthands are expanded. This step is very lenient about the sidebars' shapes. Returns `NormalizedSidebars`.
+3. **Validation**. The normalized sidebars are validated. This step happens after normalization, because the normalized sidebars are easier to validate, and allows us to repeatedly validate & generate in the future.
+4. **Generation**. This step is done through the "processor" (naming is hard). The `autogenerated` items are unwrapped. In the future, steps 3 and 4 may be repeatedly done until all autogenerated items are unwrapped. Returns `ProcessedSidebars`.
+   - **Important**: this step should only care about unwrapping autogenerated items, not filtering them, writing additional metadata, applying defaults, etc.—everything will be handled in the post-processor. Important because the generator is exposed to the end-user and we want it to be easy to be reasoned about.
+5. **Post-processing**. Defaults are applied (collapsed states), category links are resolved, empty categories are flattened. Returns `Sidebars`.