@docusaurus/plugin-content-docs 2.0.0-beta.16 → 2.0.0-beta.19

package/src/docs.ts

@@ -12,6 +12,7 @@ import {
   aliasedSitePath,
   getEditUrl,
   getFolderContainingFile,
+  getContentPathList,
   normalizeUrl,
   parseMarkdownString,
   posixPath,
@@ -21,27 +22,24 @@ import {
 import type {LoadContext} from '@docusaurus/types';
 
 import {getFileLastUpdate} from './lastUpdate';
-import type {
-  DocFile,
-  DocMetadataBase,
-  DocMetadata,
-  DocNavLink,
-  LastUpdateData,
-  VersionMetadata,
-  LoadedVersion,
-} from './types';
+import type {DocFile} from './types';
 import getSlug from './slug';
 import {CURRENT_VERSION_NAME} from './constants';
-import {getDocsDirPaths} from './versions';
 import {stripPathNumberPrefixes} from './numberPrefix';
-import {validateDocFrontMatter} from './docFrontMatter';
+import {validateDocFrontMatter} from './frontMatter';
 import type {SidebarsUtils} from './sidebars/utils';
 import {toDocNavigationLink, toNavigationLink} from './sidebars/utils';
 import type {
   MetadataOptions,
   PluginOptions,
   CategoryIndexMatcher,
-  CategoryIndexMatcherParam,
+  DocMetadataBase,
+  DocMetadata,
+  PropNavigationLink,
+  LastUpdateData,
+  VersionMetadata,
+  DocFrontMatter,
+  LoadedVersion,
 } from '@docusaurus/plugin-content-docs';
 
 type LastUpdateOptions = Pick<
@@ -85,7 +83,7 @@ export async function readDocFile(
   options: LastUpdateOptions,
 ): Promise<DocFile> {
   const contentPath = await getFolderContainingFile(
-    getDocsDirPaths(versionMetadata),
+    getContentPathList(versionMetadata),
     source,
   );
 
@@ -114,16 +112,31 @@ export async function readVersionDocs(
   );
 }
 
+export type DocEnv = 'production' | 'development';
+
+/** Docs with draft front matter are only considered draft in production. */
+function isDraftForEnvironment({
+  env,
+  frontMatter,
+}: {
+  frontMatter: DocFrontMatter;
+  env: DocEnv;
+}): boolean {
+  return (env === 'production' && frontMatter.draft) ?? false;
+}
+
 function doProcessDocMetadata({
   docFile,
   versionMetadata,
   context,
   options,
+  env,
 }: {
   docFile: DocFile;
   versionMetadata: VersionMetadata;
   context: LoadContext;
   options: MetadataOptions;
+  env: DocEnv;
 }): DocMetadataBase {
   const {source, content, lastUpdate, contentPath, filePath} = docFile;
   const {siteDir, i18n} = context;
@@ -144,15 +157,13 @@ function doProcessDocMetadata({
     parse_number_prefixes: parseNumberPrefixes = true,
   } = frontMatter;
 
-  // ex: api/plugins/myDoc -> myDoc
-  // ex: myDoc -> myDoc
+  // E.g. api/plugins/myDoc -> myDoc; myDoc -> myDoc
   const sourceFileNameWithoutExtension = path.basename(
     source,
     path.extname(source),
   );
 
-  // ex: api/plugins/myDoc -> api/plugins
-  // ex: myDoc -> .
+  // E.g. api/plugins/myDoc -> api/plugins; myDoc -> .
   const sourceDirName = path.dirname(source);
 
   const {filename: unprefixedFileName, numberPrefix} = parseNumberPrefixes
@@ -213,7 +224,7 @@ function doProcessDocMetadata({
 
   const description: string = frontMatter.description ?? excerpt ?? '';
 
-  const permalink = normalizeUrl([versionMetadata.versionPath, docSlug]);
+  const permalink = normalizeUrl([versionMetadata.path, docSlug]);
 
   function getDocEditUrl() {
     const relativeFilePath = path.relative(contentPath, filePath);
@@ -232,13 +243,15 @@ function doProcessDocMetadata({
       const isLocalized = contentPath === versionMetadata.contentPathLocalized;
       const baseVersionEditUrl =
         isLocalized && options.editLocalizedFiles
-          ? versionMetadata.versionEditUrlLocalized
-          : versionMetadata.versionEditUrl;
+          ? versionMetadata.editUrlLocalized
+          : versionMetadata.editUrl;
       return getEditUrl(relativeFilePath, baseVersionEditUrl);
     }
     return undefined;
   }
 
+  const draft = isDraftForEnvironment({env, frontMatter});
+
   // Assign all of object properties during instantiation (if possible) for
   // NodeJS optimization.
   // Adding properties to object after instantiation will cause hidden
@@ -252,15 +265,16 @@ function doProcessDocMetadata({
     sourceDirName,
     slug: docSlug,
     permalink,
+    draft,
     editUrl: customEditURL !== undefined ? customEditURL : getDocEditUrl(),
     tags: normalizeFrontMatterTags(versionMetadata.tagsPath, frontMatter.tags),
     version: versionMetadata.versionName,
     lastUpdatedBy: lastUpdate.lastUpdatedBy,
     lastUpdatedAt: lastUpdate.lastUpdatedAt,
     formattedLastUpdatedAt: lastUpdate.lastUpdatedAt
-      ? new Intl.DateTimeFormat(i18n.currentLocale).format(
-          lastUpdate.lastUpdatedAt * 1000,
-        )
+      ? new Intl.DateTimeFormat(i18n.currentLocale, {
+          calendar: i18n.localeConfigs[i18n.currentLocale]!.calendar,
+        }).format(lastUpdate.lastUpdatedAt * 1000)
       : undefined,
     sidebarPosition,
     frontMatter,
@@ -272,6 +286,7 @@ export function processDocMetadata(args: {
   versionMetadata: VersionMetadata;
   context: LoadContext;
   options: MetadataOptions;
+  env: DocEnv;
 }): DocMetadataBase {
   try {
     return doProcessDocMetadata(args);
@@ -304,7 +319,7 @@ export function addDocNavigation(
     const toNavigationLinkByDocId = (
       docId: string | null | undefined,
       type: 'prev' | 'next',
-    ): DocNavLink | undefined => {
+    ): PropNavigationLink | undefined => {
       if (!docId) {
         return undefined;
       }
@@ -331,7 +346,7 @@ export function addDocNavigation(
   }
 
   const docsWithNavigation = docsBase.map(addNavData);
-  // sort to ensure consistent output for tests
+  // Sort to ensure consistent output for tests
   docsWithNavigation.sort((a, b) => a.id.localeCompare(b.id));
   return docsWithNavigation;
 }
@@ -363,7 +378,7 @@ export function getMainDocId({
           doc.unversionedId === firstDocIdOfFirstSidebar,
       )!;
     }
-    return docs[0];
+    return docs[0]!;
   }
 
   return getMainDoc().unversionedId;
@@ -391,13 +406,17 @@ export const isCategoryIndex: CategoryIndexMatcher = ({
   return eligibleDocIndexNames.includes(fileName.toLowerCase());
 };
 
+/**
+ * `guides/sidebar/autogenerated.md` ->
+ *   `'autogenerated', '.md', ['sidebar', 'guides']`
+ */
 export function toCategoryIndexMatcherParam({
   source,
   sourceDirName,
 }: Pick<
   DocMetadataBase,
   'source' | 'sourceDirName'
->): CategoryIndexMatcherParam {
+>): Parameters<CategoryIndexMatcher>[0] {
   // source + sourceDirName are always posix-style
   return {
     fileName: path.posix.parse(source).name,
@@ -406,28 +425,6 @@ export function toCategoryIndexMatcherParam({
   };
 }
 
-/**
- * `guides/sidebar/autogenerated.md` ->
- *   `'autogenerated', '.md', ['sidebar', 'guides']`
- */
-export function splitPath(str: string): {
-  /**
-   * The list of directories, from lowest level to highest.
-   * If there's no dir name, directories is ['.']
-   */
-  directories: string[];
-  /** The file name, without extension */
-  fileName: string;
-  /** The extension, with a leading dot */
-  extension: string;
-} {
-  return {
-    fileName: path.parse(str).name,
-    extension: path.parse(str).ext,
-    directories: path.dirname(str).split(path.sep).reverse(),
-  };
-}
-
 // Return both doc ids
 // TODO legacy retro-compatibility due to old versioned sidebars using
 // versioned doc ids ("id" should be removed & "versionedId" should be renamed
@@ -436,13 +433,13 @@ export function getDocIds(doc: DocMetadataBase): [string, string] {
   return [doc.unversionedId, doc.id];
 }
 
-// docs are indexed by both versioned and unversioned ids at the same time
+// Docs are indexed by both versioned and unversioned ids at the same time
 // TODO legacy retro-compatibility due to old versioned sidebars using
 // versioned doc ids ("id" should be removed & "versionedId" should be renamed
 // to "id")
 export function createDocsByIdIndex<
   Doc extends {id: string; unversionedId: string},
->(docs: Doc[]): Record<string, Doc> {
+>(docs: Doc[]): {[docId: string]: Doc} {
   return Object.fromEntries(
     docs.flatMap((doc) => [
       [doc.unversionedId, doc],

package/src/{docFrontMatter.ts → frontMatter.ts}

@@ -12,7 +12,7 @@ import {
   FrontMatterTOCHeadingLevels,
   validateFrontMatter,
 } from '@docusaurus/utils-validation';
-import type {DocFrontMatter} from './types';
+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
@@ -20,12 +20,14 @@ import type {DocFrontMatter} from './types';
 // We use default values in code instead
 const DocFrontMatterSchema = Joi.object<DocFrontMatter>({
   id: Joi.string(),
-  title: Joi.string().allow(''), // see https://github.com/facebook/docusaurus/issues/4591#issuecomment-822372398
+  // 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,
-  description: Joi.string().allow(''), // see  https://github.com/facebook/docusaurus/issues/4591#issuecomment-822372398
+  // See https://github.com/facebook/docusaurus/issues/4591#issuecomment-822372398
+  description: Joi.string().allow(''),
   slug: Joi.string(),
   sidebar_label: Joi.string(),
   sidebar_position: Joi.number(),
@@ -38,11 +40,12 @@ const DocFrontMatterSchema = Joi.object<DocFrontMatter>({
   parse_number_prefixes: Joi.boolean(),
   pagination_next: Joi.string().allow(null),
   pagination_prev: Joi.string().allow(null),
+  draft: Joi.boolean(),
   ...FrontMatterTOCHeadingLevels,
 }).unknown();
 
-export function validateDocFrontMatter(
-  frontMatter: Record<string, unknown>,
-): DocFrontMatter {
+export function validateDocFrontMatter(frontMatter: {
+  [key: string]: unknown;
+}): DocFrontMatter {
   return validateFrontMatter(frontMatter, DocFrontMatterSchema);
 }

package/src/globalData.ts

@@ -6,21 +6,20 @@
  */
 
 import _ from 'lodash';
-import {normalizeUrl} from '@docusaurus/utils';
 import type {Sidebars} from './sidebars/types';
-import {createSidebarsUtils} from './sidebars/utils';
+import {getMainDocId} from './docs';
+import type {FullVersion} from './types';
 import type {
   CategoryGeneratedIndexMetadata,
   DocMetadata,
-  LoadedVersion,
-} from './types';
+} from '@docusaurus/plugin-content-docs';
 import type {
   GlobalVersion,
   GlobalSidebar,
   GlobalDoc,
 } from '@docusaurus/plugin-content-docs/client';
 
-export function toGlobalDataDoc(doc: DocMetadata): GlobalDoc {
+function toGlobalDataDoc(doc: DocMetadata): GlobalDoc {
   return {
     id: doc.unversionedId,
     path: doc.permalink,
@@ -28,7 +27,7 @@ export function toGlobalDataDoc(doc: DocMetadata): GlobalDoc {
   };
 }
 
-export function toGlobalDataGeneratedIndex(
+function toGlobalDataGeneratedIndex(
   doc: CategoryGeneratedIndexMetadata,
 ): GlobalDoc {
   return {
@@ -38,13 +37,12 @@ export function toGlobalDataGeneratedIndex(
   };
 }
 
-export function toGlobalSidebars(
+function toGlobalSidebars(
   sidebars: Sidebars,
-  version: LoadedVersion,
-): Record<string, GlobalSidebar> {
-  const {getFirstLink} = createSidebarsUtils(sidebars);
+  version: FullVersion,
+): {[sidebarId: string]: GlobalSidebar} {
   return _.mapValues(sidebars, (sidebar, sidebarId) => {
-    const firstLink = getFirstLink(sidebarId);
+    const firstLink = version.sidebarsUtils.getFirstLink(sidebarId);
     if (!firstLink) {
       return {};
     }
@@ -52,7 +50,7 @@ export function toGlobalSidebars(
       link: {
         path:
           firstLink.type === 'generated-index'
-            ? normalizeUrl([version.versionPath, firstLink.slug])
+            ? firstLink.permalink
             : version.docs.find(
                 (doc) =>
                   doc.id === firstLink.id || doc.unversionedId === firstLink.id,
@@ -63,16 +61,17 @@ export function toGlobalSidebars(
   });
 }
 
-export function toGlobalDataVersion(version: LoadedVersion): GlobalVersion {
+export function toGlobalDataVersion(version: FullVersion): GlobalVersion {
   return {
     name: version.versionName,
-    label: version.versionLabel,
+    label: version.label,
     isLast: version.isLast,
-    path: version.versionPath,
-    mainDocId: version.mainDocId,
+    path: version.path,
+    mainDocId: getMainDocId(version),
     docs: version.docs
       .map(toGlobalDataDoc)
       .concat(version.categoryGeneratedIndices.map(toGlobalDataGeneratedIndex)),
+    draftIds: version.drafts.map((doc) => doc.unversionedId),
     sidebars: toGlobalSidebars(version.sidebars, version),
   };
 }

package/src/index.ts

@@ -11,6 +11,7 @@ import {
   normalizeUrl,
   docuHash,
   aliasedSitePath,
+  getContentPathList,
   reportMessage,
   posixPath,
   addTrailingPathSeparator,
@@ -19,32 +20,24 @@ import {
   DEFAULT_PLUGIN_ID,
 } from '@docusaurus/utils';
 import type {LoadContext, Plugin} from '@docusaurus/types';
-import {loadSidebars} from './sidebars';
+import {loadSidebars, resolveSidebarPathOption} from './sidebars';
 import {CategoryMetadataFilenamePattern} from './sidebars/generator';
-import {
-  readVersionDocs,
-  processDocMetadata,
-  addDocNavigation,
-  getMainDocId,
-} from './docs';
-import {getDocsDirPaths, readVersionsMetadata} from './versions';
-
+import type {DocEnv} from './docs';
+import {readVersionDocs, processDocMetadata, addDocNavigation} from './docs';
+import {readVersionsMetadata} from './versions';
 import type {
-  LoadedContent,
   SourceToPermalink,
-  DocMetadataBase,
-  VersionMetadata,
-  LoadedVersion,
   DocFile,
   DocsMarkdownOption,
   VersionTag,
-  DocFrontMatter,
+  FullVersion,
 } from './types';
 import type {RuleSetRule} from 'webpack';
 import {cliDocsVersionCommand} from './cli';
 import {VERSIONS_JSON_FILE} from './constants';
 import {toGlobalDataVersion} from './globalData';
 import {toTagDocListProp} from './props';
+import {getCategoryGeneratedIndexMetadataList} from './categoryGeneratedIndex';
 import {
   translateLoadedContent,
   getLoadedContentTranslationFiles,
@@ -55,20 +48,26 @@ import {createVersionRoutes} from './routes';
 import type {
   PropTagsListPage,
   PluginOptions,
+  DocMetadataBase,
+  VersionMetadata,
+  DocFrontMatter,
+  LoadedContent,
+  LoadedVersion,
 } from '@docusaurus/plugin-content-docs';
-import type {GlobalPluginData} from '@docusaurus/plugin-content-docs/client';
 import {createSidebarsUtils} from './sidebars/utils';
-import {getCategoryGeneratedIndexMetadataList} from './categoryGeneratedIndex';
+import _ from 'lodash';
 
 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 ?? DEFAULT_PLUGIN_ID;
+  const pluginId = options.id;
 
   const pluginDataDirRoot = path.join(
     generatedFilesDir,
@@ -98,16 +97,11 @@ export default async function pluginContentDocs(
         .arguments('<version>')
         .description(commandDescription)
         .action((version) => {
-          cliDocsVersionCommand(version, siteDir, pluginId, {
-            path: options.path,
-            sidebarPath: options.sidebarPath,
-            sidebarCollapsed: options.sidebarCollapsed,
-            sidebarCollapsible: options.sidebarCollapsible,
-          });
+          cliDocsVersionCommand(version, options, context);
         });
     },
 
-    async getTranslationFiles({content}) {
+    getTranslationFiles({content}) {
       return getLoadedContentTranslationFiles(content);
     },
 
@@ -115,7 +109,7 @@ export default async function pluginContentDocs(
       function getVersionPathsToWatch(version: VersionMetadata): string[] {
         const result = [
           ...options.include.flatMap((pattern) =>
-            getDocsDirPaths(version).map(
+            getContentPathList(version).map(
               (docsDirPath) => `${docsDirPath}/${pattern}`,
             ),
           ),
@@ -151,6 +145,7 @@ export default async function pluginContentDocs(
             versionMetadata,
             context,
             options,
+            env: process.env.NODE_ENV as DocEnv,
           });
         }
         return Promise.all(docFiles.map(processVersionDoc));
@@ -159,14 +154,17 @@ export default async function pluginContentDocs(
       async function doLoadVersion(
         versionMetadata: VersionMetadata,
       ): Promise<LoadedVersion> {
-        const docs: DocMetadataBase[] = await loadVersionDocsBase(
+        const docsBase: DocMetadataBase[] = await loadVersionDocsBase(
           versionMetadata,
         );
 
+        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,
@@ -184,12 +182,8 @@ export default async function pluginContentDocs(
             sidebarsUtils,
             versionMetadata.sidebarFilePath as string,
           ),
+          drafts,
           sidebars,
-          mainDocId: getMainDocId({docs, sidebarsUtils}),
-          categoryGeneratedIndices: getCategoryGeneratedIndexMetadataList({
-            docs,
-            sidebarsUtils,
-          }),
         };
       }
 
@@ -220,8 +214,19 @@ export default async function pluginContentDocs(
         breadcrumbs,
       } = options;
       const {addRoute, createData, setGlobalData} = actions;
+      const versions: FullVersion[] = loadedVersions.map((version) => {
+        const sidebarsUtils = createSidebarsUtils(version.sidebars);
+        return {
+          ...version,
+          sidebarsUtils,
+          categoryGeneratedIndices: getCategoryGeneratedIndexMetadataList({
+            docs: version.docs,
+            sidebarsUtils,
+          }),
+        };
+      });
 
-      async function createVersionTagsRoutes(version: LoadedVersion) {
+      async function createVersionTagsRoutes(version: FullVersion) {
         const versionTags = getVersionTags(version.docs);
 
         // TODO tags should be a sub route of the version route
@@ -229,13 +234,13 @@ export default async function pluginContentDocs(
           const tagsProp: PropTagsListPage['tags'] = Object.values(
             versionTags,
           ).map((tagValue) => ({
-            name: tagValue.name,
+            label: tagValue.label,
             permalink: tagValue.permalink,
             count: tagValue.docIds.length,
           }));
 
           // Only create /tags page if there are tags.
-          if (Object.keys(tagsProp).length > 0) {
+          if (tagsProp.length > 0) {
             const tagsPropPath = await createData(
               `${docuHash(`tags-list-${version.versionName}-prop`)}.json`,
               JSON.stringify(tagsProp, null, 2),
@@ -277,9 +282,9 @@ export default async function pluginContentDocs(
       }
 
       await Promise.all(
-        loadedVersions.map((loadedVersion) =>
+        versions.map((version) =>
           createVersionRoutes({
-            loadedVersion,
+            version,
             docItemComponent,
             docLayoutComponent,
             docCategoryGeneratedIndexComponent,
@@ -291,11 +296,11 @@ export default async function pluginContentDocs(
       );
 
       // TODO tags should be a sub route of the version route
-      await Promise.all(loadedVersions.map(createVersionTagsRoutes));
+      await Promise.all(versions.map(createVersionTagsRoutes));
 
-      setGlobalData<GlobalPluginData>({
+      setGlobalData({
         path: normalizeUrl([baseUrl, options.routeBasePath]),
-        versions: loadedVersions.map(toGlobalDataVersion),
+        versions: versions.map(toGlobalDataVersion),
         breadcrumbs,
       });
     },
@@ -332,7 +337,7 @@ export default async function pluginContentDocs(
       };
 
       function createMDXLoaderRule(): RuleSetRule {
-        const contentDirs = versionsMetadata.flatMap(getDocsDirPaths);
+        const contentDirs = versionsMetadata.flatMap(getContentPathList);
         return {
           test: /\.mdx?$/i,
           include: contentDirs

package/src/lastUpdate.ts

@@ -6,15 +6,18 @@
  */
 
 import logger from '@docusaurus/logger';
-import {getFileCommitDate, GitNotFoundError} from '@docusaurus/utils';
-
-type FileLastUpdateData = {timestamp?: number; author?: string};
+import {
+  getFileCommitDate,
+  FileNotTrackedError,
+  GitNotFoundError,
+} from '@docusaurus/utils';
 
 let showedGitRequirementError = false;
+let showedFileNotTrackedError = false;
 
 export async function getFileLastUpdate(
   filePath?: string,
-): Promise<FileLastUpdateData | null> {
+): Promise<{timestamp: number; author: string} | null> {
   if (!filePath) {
     return null;
   }
@@ -28,11 +31,20 @@ export async function getFileLastUpdate(
     });
     return {timestamp: result.timestamp, author: result.author};
   } catch (err) {
-    if (err instanceof GitNotFoundError && !showedGitRequirementError) {
-      logger.warn('Sorry, the docs plugin last update options require Git.');
-      showedGitRequirementError = true;
+    if (err instanceof GitNotFoundError) {
+      if (!showedGitRequirementError) {
+        logger.warn('Sorry, the docs plugin last update options require Git.');
+        showedGitRequirementError = true;
+      }
+    } else if (err instanceof FileNotTrackedError) {
+      if (!showedFileNotTrackedError) {
+        logger.warn(
+          'Cannot infer the update date for some files, as they are not tracked by git.',
+        );
+        showedFileNotTrackedError = true;
+      }
     } else {
-      logger.error(err);
+      logger.warn(err);
     }
     return null;
   }

package/src/markdown/index.ts

@@ -16,7 +16,5 @@ export default function markdownLoader(
   const fileString = source;
   const callback = this.async();
   const options = this.getOptions();
-  return (
-    callback && callback(null, linkify(fileString, this.resourcePath, options))
-  );
+  return callback?.(null, linkify(fileString, this.resourcePath, options));
 }

package/src/markdown/linkify.ts

@@ -6,15 +6,18 @@
  */
 
 import type {DocsMarkdownOption} from '../types';
-import {getDocsDirPaths} from '../versions';
-import {replaceMarkdownLinks} from '@docusaurus/utils';
+import {replaceMarkdownLinks, getContentPathList} from '@docusaurus/utils';
 
 function getVersion(filePath: string, options: DocsMarkdownOption) {
   const versionFound = options.versionsMetadata.find((version) =>
-    getDocsDirPaths(version).some((docsDirPath) =>
+    getContentPathList(version).some((docsDirPath) =>
       filePath.startsWith(docsDirPath),
     ),
   );
+  // At this point, this should never happen, because the MDX loaders' paths are
+  // literally using the version content paths; but if we allow sourcing content
+  // from outside the docs directory (through the `include` option, for example;
+  // is there a compelling use-case?), this would actually be testable
   if (!versionFound) {
     throw new Error(
       `Unexpected error: Markdown file at "${filePath}" does not belong to any docs version!`,