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

package/src/plugin-content-docs.d.ts

@@ -6,128 +6,488 @@
  */
 
 declare module '@docusaurus/plugin-content-docs' {
-  import type {RemarkAndRehypePluginOptions} from '@docusaurus/mdx-loader';
-
-  export interface Assets {
+  import type {MDXOptions} from '@docusaurus/mdx-loader';
+  import type {
+    ContentPaths,
+    FrontMatterTag,
+    TagsListItem,
+    TagModule,
+    Tag,
+  } from '@docusaurus/utils';
+  import type {Plugin, LoadContext} from '@docusaurus/types';
+  import type {Required} from 'utility-types';
+
+  export type Assets = {
     image?: string;
-  }
+  };
 
+  /**
+   * Custom callback for parsing number prefixes from file/folder names.
+   */
   export type NumberPrefixParser = (filename: string) => {
+    /** File name without number prefix, without any other modification. */
     filename: string;
+    /** The number prefix. Can be float, integer, negative, or anything. */
     numberPrefix?: number;
   };
 
-  export type CategoryIndexMatcherParam = {
+  export type CategoryIndexMatcher = (param: {
+    /** The file name, without extension */
     fileName: string;
+    /**
+     * The list of directories, from lowest level to highest.
+     * If there's no dir name, directories is ['.']
+     */
     directories: string[];
+    /** The extension, with a leading dot */
     extension: string;
-  };
-  export type CategoryIndexMatcher = (
-    param: CategoryIndexMatcherParam,
-  ) => boolean;
+  }) => boolean;
 
   export type EditUrlFunction = (editUrlParams: {
+    /** Name of the version. */
     version: string;
+    /**
+     * Path of the version's root content path, relative to the site directory.
+     * Usually the same as `options.path` but can be localized or versioned.
+     */
     versionDocsDirPath: string;
+    /** Path of the doc file, relative to `versionDocsDirPath`. */
     docPath: string;
+    /** @see {@link DocMetadata.permalink} */
     permalink: string;
+    /** Locale name. */
     locale: string;
   }) => string | undefined;
 
   export type MetadataOptions = {
+    /**
+     * URL route for the docs section of your site. **DO NOT** include a
+     * trailing slash. Use `/` for shipping docs without base path.
+     */
     routeBasePath: string;
+    /**
+     * Base URL to edit your site. The final URL is computed by `editUrl +
+     * relativeDocPath`. Using a function allows more nuanced control for each
+     * file. Omitting this variable entirely will disable edit links.
+     */
     editUrl?: string | EditUrlFunction;
+    /**
+     * The edit URL will always target the current version doc instead of older
+     * versions. Ignored when `editUrl` is a function.
+     */
     editCurrentVersion: boolean;
+    /**
+     * The edit URL will target the localized file, instead of the original
+     * unlocalized file. Ignored when `editUrl` is a function.
+     */
     editLocalizedFiles: boolean;
+    /**	Whether to display the last date the doc was updated. */
     showLastUpdateTime?: boolean;
+    /** Whether to display the author who last updated the doc. */
     showLastUpdateAuthor?: boolean;
+    /**
+     * Custom parsing logic to extract number prefixes from file names. Use
+     * `false` to disable this behavior and leave the docs untouched, and `true`
+     * to use the default parser.
+     *
+     * @param filename One segment of the path, without any slashes.
+     * @see https://docusaurus.io/docs/sidebar#using-number-prefixes
+     */
     numberPrefixParser: NumberPrefixParser;
+    /** Enable or disable the breadcrumbs on doc pages. */
     breadcrumbs: boolean;
   };
 
   export type PathOptions = {
+    /**
+     * Path to the docs content directory on the file system, relative to site
+     * directory.
+     */
     path: string;
+    /**
+     * Path to sidebar configuration. Use `false` to disable sidebars, or
+     * `undefined` to create a fully autogenerated sidebar.
+     */
     sidebarPath?: string | false | undefined;
   };
 
   // TODO support custom version banner?
   // {type: "error", content: "html content"}
   export type VersionBanner = 'unreleased' | 'unmaintained';
-  export type VersionOptions = {
-    path?: string;
-    label?: string;
-    banner?: 'none' | VersionBanner;
-    badge?: boolean;
-    className?: string;
-  };
   export type VersionsOptions = {
+    /**
+     * The version navigated to in priority and displayed by default for docs
+     * navbar items.
+     *
+     * @see https://docusaurus.io/docs/versioning#terminology
+     */
     lastVersion?: string;
-    versions: Record<string, VersionOptions>;
+    /** Only include a subset of all available versions. */
     onlyIncludeVersions?: string[];
+    /**
+     * Explicitly disable versioning even when multiple versions exist. This
+     * will make the site only include the current version. Will error if
+     * `includeCurrentVersion: false` and `disableVersioning: true`.
+     */
+    disableVersioning: boolean;
+    /** Include the current version of your docs. */
+    includeCurrentVersion: boolean;
+    /** Independent customization of each version's properties. */
+    versions: {
+      [versionName: string]: {
+        /**
+         * The base path of the version, will be appended to `baseUrl` +
+         * `routeBasePath`.
+         */
+        path?: string;
+        /** The label of the version to be used in badges, dropdowns, etc. */
+        label?: string;
+        /** The banner to show at the top of a doc of that version. */
+        banner?: 'none' | VersionBanner;
+        /** Show a badge with the version label at the top of each doc. */
+        badge?: boolean;
+        /** Add a custom class name to the <html> element of each doc. */
+        className?: string;
+      };
+    };
   };
   export type SidebarOptions = {
+    /**
+     * Whether sidebar categories are collapsible by default.
+     *
+     * @see https://docusaurus.io/docs/sidebar#collapsible-categories
+     */
     sidebarCollapsible: boolean;
+    /**
+     * Whether sidebar categories are collapsed by default.
+     *
+     * @see https://docusaurus.io/docs/sidebar#expanded-categories-by-default
+     */
     sidebarCollapsed: boolean;
   };
 
   export type PluginOptions = MetadataOptions &
     PathOptions &
     VersionsOptions &
-    RemarkAndRehypePluginOptions &
+    MDXOptions &
     SidebarOptions & {
+      /** Plugin ID. */
       id: string;
+      /**
+       * Array of glob patterns matching Markdown files to be built, relative to
+       * the content path.
+       */
       include: string[];
+      /**
+       * Array of glob patterns matching Markdown files to be excluded. Serves
+       * as refinement based on the `include` option.
+       */
       exclude: string[];
+      /**
+       * Root layout component of each doc page. Provides the version data
+       * context, and is not unmounted when switching docs.
+       */
       docLayoutComponent: string;
+      /** Main doc container, with TOC, pagination, etc. */
       docItemComponent: string;
+      /** Root component of the "docs containing tag X" page. */
       docTagDocListComponent: string;
+      /** Root component of the tags list page */
       docTagsListComponent: string;
+      /** Root component of the generated category index page. */
       docCategoryGeneratedIndexComponent: string;
-      admonitions: Record<string, unknown>;
-      disableVersioning: boolean;
-      includeCurrentVersion: boolean;
+      admonitions: {[key: string]: unknown};
       sidebarItemsGenerator: import('./sidebars/types').SidebarItemsGeneratorOption;
+      /**
+       * URL route for the tags section of your doc version. Will be appended to
+       * `routeBasePath`. **DO NOT** include a trailing slash.
+       */
       tagsBasePath: string;
     };
   export type Options = Partial<PluginOptions>;
   export type SidebarsConfig = import('./sidebars/types').SidebarsConfig;
 
+  export type VersionMetadata = ContentPaths & {
+    /** A name like `1.0.0`. Acquired from `versions.json`. */
+    versionName: string;
+    /** Like `Version 1.0.0`. Can be configured through `versions.label`. */
+    label: string;
+    /**
+     * Version's base path in the form of `/<baseUrl>/<routeBasePath>/1.0.0`.
+     * Can be configured through `versions.path`.
+     */
+    path: string;
+    /** Tags base path in the form of `<versionPath>/tags`. */
+    tagsPath: string;
+    /**
+     * The base URL to which the doc file path will be appended. Will be
+     * `undefined` if `editUrl` is `undefined` or a function.
+     */
+    editUrl?: string | undefined;
+    /**
+     * The base URL to which the localized doc file path will be appended. Will
+     * be `undefined` if `editUrl` is `undefined` or a function.
+     */
+    editUrlLocalized?: string | undefined;
+    /**
+     * "unmaintained" is the version before latest; "unreleased" is the version
+     * after latest. `null` is the latest version without a banner. Can be
+     * configured with `versions.banner`: `banner: "none"` will be transformed
+     * to `null` here.
+     */
+    banner: VersionBanner | null;
+    /** Show a badge with the version label at the top of each doc. */
+    badge: boolean;
+    /** Add a custom class name to the <html> element of each doc. */
+    className: string;
+    /**
+     * Whether this version is the "last" version. Can be configured with
+     * `lastVersion` option.
+     */
+    isLast: boolean;
+    /**
+     * Like `versioned_sidebars/1.0.0.json`. Versioned sidebars file may be
+     * nonexistent since we don't create empty files.
+     */
+    sidebarFilePath: string | false | undefined;
+    /**
+     * Will be -1 for the latest docs, and `undefined` for everything else.
+     * Because `/docs/foo` should always be after `/docs/<versionName>/foo`.
+     */
+    routePriority: number | undefined;
+  };
+
+  export type DocFrontMatter = {
+    /**
+     * The last part of the doc ID (will be refactored in the future to be the
+     * full ID instead)
+     * @see {@link DocMetadata.id}
+     */
+    id?: string;
+    /**
+     * Will override the default title collected from h1 heading.
+     * @see {@link DocMetadata.title}
+     */
+    title?: string;
+    /**
+     * Front matter tags, unnormalized.
+     * @see {@link DocMetadata.tags}
+     */
+    tags?: FrontMatterTag[];
+    /**
+     * If there isn't a Markdown h1 heading (which, if there is, we don't
+     * remove), this front matter will cause the front matter title to not be
+     * displayed in the doc page.
+     */
+    hide_title?: boolean;
+    /** Hide the TOC on the right. */
+    hide_table_of_contents?: boolean;
+    /** Used in the head meta. */
+    keywords?: string[];
+    /** Used in the head meta. Should use `assets.image` in priority. */
+    image?: string;
+    /**
+     * Will override the default excerpt.
+     * @see {@link DocMetadata.description}
+     */
+    description?: string;
+    /**
+     * Custom slug appended after /<baseUrl>/<routeBasePath>/<versionPath>
+     * @see {@link DocMetadata.slug}
+     */
+    slug?: string;
+    /** Customizes the sidebar label for this doc. Will default to its title. */
+    sidebar_label?: string;
+    /**
+     * Controls the position of a doc inside the generated sidebar slice when
+     * using autogenerated sidebar items.
+     *
+     * @see https://docusaurus.io/docs/sidebar#autogenerated-sidebar-metadata
+     */
+    sidebar_position?: number;
+    /**
+     * Gives the corresponding sidebar label a special class name when using
+     * autogenerated sidebars.
+     */
+    sidebar_class_name?: string;
+    /**
+     * Will be propagated to the final sidebars data structure. Useful if you
+     * have swizzled sidebar-related code or simply querying doc data through
+     * sidebars.
+     */
+    sidebar_custom_props?: {[key: string]: unknown};
+    /**
+     * Changes the sidebar association of the current doc. Use `null` to make
+     * the current doc not associated to any sidebar.
+     */
+    displayed_sidebar?: string | null;
+    /**
+     * Customizes the pagination label for this doc. Will default to the sidebar
+     * label.
+     */
+    pagination_label?: string;
+    /** Overrides the default URL computed for this doc. */
+    custom_edit_url?: string | null;
+    /**
+     * Whether number prefix parsing is disabled on this doc.
+     * @see https://docusaurus.io/docs/sidebar#using-number-prefixes
+     */
+    parse_number_prefixes?: boolean;
+    /**
+     * Minimum TOC heading level. Must be between 2 and 6 and lower or equal to
+     * the max value.
+     */
+    toc_min_heading_level?: number;
+    /** Maximum TOC heading level. Must be between 2 and 6. */
+    toc_max_heading_level?: number;
+    /**
+     * The ID of the documentation you want the "Next" pagination to link to.
+     * Use `null` to disable showing "Next" for this page.
+     * @see {@link DocMetadata.next}
+     */
+    pagination_next?: string | null;
+    /**
+     * The ID of the documentation you want the "Previous" pagination to link
+     * to. Use `null` to disable showing "Previous" for this page.
+     * @see {@link DocMetadata.prev}
+     */
+    pagination_prev?: string | null;
+    /** Should this doc be excluded from production builds? */
+    draft?: boolean;
+  };
+
+  export type LastUpdateData = {
+    /** A timestamp in **seconds**, directly acquired from `git log`. */
+    lastUpdatedAt?: number;
+    /** `lastUpdatedAt` formatted as a date according to the current locale. */
+    formattedLastUpdatedAt?: string;
+    /** The author's name directly acquired from `git log`. */
+    lastUpdatedBy?: string;
+  };
+
+  export type DocMetadataBase = LastUpdateData & {
+    // TODO
+    /**
+     * Legacy versioned ID. Will be refactored in the future to be unversioned.
+     */
+    id: string;
+    // TODO
+    /**
+     * Unversioned ID. Should be preferred everywhere over `id` until the latter
+     * is refactored.
+     */
+    unversionedId: string;
+    /** The name of the version this doc belongs to. */
+    version: string;
+    /**
+     * Used to generate the page h1 heading, tab title, and pagination title.
+     */
+    title: string;
+    /**
+     * Description used in the meta. Could be an empty string (empty content)
+     */
+    description: string;
+    /** Path to the Markdown source, with `@site` alias. */
+    source: string;
+    /**
+     * Posix path relative to the content path. Can be `"."`.
+     * e.g. "folder/subfolder/subsubfolder"
+     */
+    sourceDirName: string;
+    /** `permalink` without base URL or version path. */
+    slug: string;
+    /** Full URL to this doc, with base URL and version path. */
+    permalink: string;
+    /**
+     * Draft docs will be excluded for production environment.
+     */
+    draft: boolean;
+    /**
+     * Position in an autogenerated sidebar slice, acquired through front matter
+     * or number prefix.
+     */
+    sidebarPosition?: number;
+    /**
+     * Acquired from the options; can be customized with front matter.
+     * `custom_edit_url` will always lead to it being null, but you should treat
+     * `undefined` and `null` as equivalent.
+     */
+    editUrl?: string | null;
+    /** Tags, normalized. */
+    tags: Tag[];
+    /** Front matter, as-is. */
+    frontMatter: DocFrontMatter & {[key: string]: unknown};
+  };
+
+  export type DocMetadata = DocMetadataBase &
+    PropNavigation & {
+      /** Name of the sidebar this doc is associated with. */
+      sidebar?: string;
+    };
+
+  export type CategoryGeneratedIndexMetadata = Required<
+    Omit<
+      import('./sidebars/types').SidebarItemCategoryLinkGeneratedIndex,
+      'type'
+    >,
+    'title'
+  > & {
+    navigation: PropNavigation;
+    /**
+     * Name of the sidebar this doc is associated with. Unlike
+     * `DocMetadata.sidebar`, this will always be defined, because a generated
+     * index can only be generated from a category.
+     */
+    sidebar: string;
+  };
+
   export type PropNavigationLink = {
     readonly title: string;
     readonly permalink: string;
   };
   export type PropNavigation = {
+    /**
+     * Used in pagination. Content is just a subset of another doc's metadata.
+     */
     readonly previous?: PropNavigationLink;
+    /**
+     * Used in pagination. Content is just a subset of another doc's metadata.
+     */
     readonly next?: PropNavigationLink;
   };
 
-  export type PropVersionDoc = import('./sidebars/types').PropVersionDoc;
-  export type PropVersionDocs = import('./sidebars/types').PropVersionDocs;
+  export type PropVersionDoc = Pick<
+    DocMetadata,
+    'id' | 'title' | 'description' | 'sidebar'
+  >;
+
+  export type PropVersionDocs = {
+    [docId: string]: PropVersionDoc;
+  };
 
-  export type PropVersionMetadata = {
+  export type PropVersionMetadata = Pick<
+    VersionMetadata,
+    'label' | 'banner' | 'badge' | 'className' | 'isLast'
+  > & {
+    /** ID of the docs plugin this version belongs to. */
     pluginId: string;
+    /** Name of this version. */
     version: string;
-    label: string;
-    banner: VersionBanner | null;
-    badge: boolean;
-    className: string;
-    isLast: boolean;
+    /** Sidebars contained in this version. */
     docsSidebars: PropSidebars;
+    /** Docs contained in this version. */
     docs: PropVersionDocs;
   };
 
-  export type PropCategoryGeneratedIndex = {
-    title: string;
-    description?: string;
-    image?: string;
-    keywords?: string | readonly string[];
-    slug: string;
-    permalink: string;
-    navigation: PropNavigation;
-  };
+  export type PropCategoryGeneratedIndex = Omit<
+    CategoryGeneratedIndexMetadata,
+    'sidebar'
+  >;
 
   export type PropSidebarItemLink =
     import('./sidebars/types').PropSidebarItemLink;
+  export type PropSidebarItemHtml =
+    import('./sidebars/types').PropSidebarItemHtml;
   export type PropSidebarItemCategory =
     import('./sidebars/types').PropSidebarItemCategory;
   export type PropSidebarItem = import('./sidebars/types').PropSidebarItem;
@@ -136,34 +496,39 @@ declare module '@docusaurus/plugin-content-docs' {
   export type PropSidebar = import('./sidebars/types').PropSidebar;
   export type PropSidebars = import('./sidebars/types').PropSidebars;
 
-  export type PropTagDocListDoc = {
-    id: string;
-    title: string;
-    description: string;
-    permalink: string;
+  export type PropTagDocListDoc = Pick<
+    DocMetadata,
+    'id' | 'title' | 'description' | 'permalink'
+  >;
+  export type PropTagDocList = TagModule & {items: PropTagDocListDoc[]};
+
+  export type PropTagsListPage = {
+    tags: TagsListItem[];
   };
-  export type PropTagDocList = {
-    allTagsPath: string;
-    name: string; // normalized name/label of the tag
-    permalink: string; // pathname of the tag
-    docs: PropTagDocListDoc[];
+
+  export type LoadedVersion = VersionMetadata & {
+    docs: DocMetadata[];
+    drafts: DocMetadata[];
+    sidebars: import('./sidebars/types').Sidebars;
   };
 
-  export type PropTagsListPage = {
-    tags: {
-      name: string;
-      permalink: string;
-      count: number;
-    }[];
+  export type LoadedContent = {
+    loadedVersions: LoadedVersion[];
   };
+
+  export default function pluginContentDocs(
+    context: LoadContext,
+    options: PluginOptions,
+  ): Promise<Plugin<LoadedContent>>;
 }
 
 declare module '@theme/DocItem' {
-  import type {TOCItem} from '@docusaurus/types';
+  import type {LoadedMDXContent} from '@docusaurus/mdx-loader';
   import type {
-    PropNavigationLink,
     PropVersionMetadata,
     Assets,
+    DocMetadata,
+    DocFrontMatter,
   } from '@docusaurus/plugin-content-docs';
 
   export type DocumentRoute = {
@@ -173,45 +538,10 @@ declare module '@theme/DocItem' {
     readonly sidebar?: string;
   };
 
-  export type FrontMatter = {
-    readonly id: string;
-    readonly title: string;
-    readonly image?: string;
-    readonly keywords?: readonly string[];
-    readonly hide_title?: boolean;
-    readonly hide_table_of_contents?: boolean;
-    readonly toc_min_heading_level?: number;
-    readonly toc_max_heading_level?: number;
-  };
-
-  export type Metadata = {
-    readonly description?: string;
-    readonly title?: string;
-    readonly permalink?: string;
-    readonly editUrl?: string;
-    readonly lastUpdatedAt?: number;
-    readonly formattedLastUpdatedAt?: string;
-    readonly lastUpdatedBy?: string;
-    readonly version?: string;
-    readonly previous?: PropNavigationLink;
-    readonly next?: PropNavigationLink;
-    readonly tags: readonly {
-      readonly label: string;
-      readonly permalink: string;
-    }[];
-  };
-
   export interface Props {
     readonly route: DocumentRoute;
     readonly versionMetadata: PropVersionMetadata;
-    readonly content: {
-      readonly frontMatter: FrontMatter;
-      readonly metadata: Metadata;
-      readonly toc: readonly TOCItem[];
-      readonly contentTitle: string | undefined;
-      readonly assets: Assets;
-      (): JSX.Element;
-    };
+    readonly content: LoadedMDXContent<DocFrontMatter, DocMetadata, Assets>;
   }
 
   export default function DocItem(props: Props): JSX.Element;
@@ -251,23 +581,21 @@ declare module '@theme/DocBreadcrumbs' {
 
 declare module '@theme/DocPage' {
   import type {PropVersionMetadata} from '@docusaurus/plugin-content-docs';
-  import type {DocumentRoute} from '@theme/DocItem';
+  import type {RouteConfigComponentProps} from 'react-router-config';
+  import type {Required} from 'utility-types';
 
-  export interface Props {
-    readonly location: {readonly pathname: string};
+  export interface Props extends Required<RouteConfigComponentProps, 'route'> {
     readonly versionMetadata: PropVersionMetadata;
-    readonly route: {
-      readonly path: string;
-      readonly component: () => JSX.Element;
-      readonly routes: DocumentRoute[];
-    };
   }
 
   export default function DocPage(props: Props): JSX.Element;
 }
 
-// TODO until TS supports exports field... hope it's in 4.6
+// TODO TS only supports reading `exports` in 4.7. We will need to merge the
+// type defs (and JSDoc) here with the implementation after that
 declare module '@docusaurus/plugin-content-docs/client' {
+  import type {UseDataOptions} from '@docusaurus/types';
+
   export type ActivePlugin = {
     pluginId: string;
     pluginData: GlobalPluginData;
@@ -275,9 +603,14 @@ declare module '@docusaurus/plugin-content-docs/client' {
   export type ActiveDocContext = {
     activeVersion?: GlobalVersion;
     activeDoc?: GlobalDoc;
-    alternateDocVersions: Record<string, GlobalDoc>;
+    alternateDocVersions: {[versionName: string]: GlobalDoc};
   };
   export type GlobalDoc = {
+    /**
+     * For generated index pages, this is the `slug`, **not** `permalink`
+     * (without base URL). Because slugs have leading slashes but IDs don't,
+     * there won't be clashes.
+     */
     id: string;
     path: string;
     sidebar: string | undefined;
@@ -288,18 +621,19 @@ declare module '@docusaurus/plugin-content-docs/client' {
     label: string;
     isLast: boolean;
     path: string;
-    mainDocId: string; // home doc (if docs homepage configured), or first doc
+    /** The doc with `slug: /`, or first doc in first sidebar */
+    mainDocId: string;
     docs: GlobalDoc[];
-    sidebars?: Record<string, GlobalSidebar>;
-  };
-
-  export type GlobalSidebarLink = {
-    label: string;
-    path: string;
+    /** Unversioned IDs. In development, this list is empty. */
+    draftIds: string[];
+    sidebars?: {[sidebarId: string]: GlobalSidebar};
   };
 
   export type GlobalSidebar = {
-    link?: GlobalSidebarLink;
+    link?: {
+      label: string;
+      path: string;
+    };
     // ... we may add other things here later
   };
   export type GlobalPluginData = {
@@ -308,29 +642,36 @@ declare module '@docusaurus/plugin-content-docs/client' {
     breadcrumbs: boolean;
   };
   export type DocVersionSuggestions = {
-    // suggest the latest version
+    /** Suggest the latest version */
     latestVersionSuggestion: GlobalVersion;
-    // suggest the same doc, in latest version (if exist)
+    /** Suggest the same doc, in latest version (if one exists) */
     latestDocSuggestion?: GlobalDoc;
   };
-  export type GetActivePluginOptions = {failfast?: boolean}; // use fail-fast option if you know for sure one plugin instance is active
 
-  export const useAllDocsData: () => Record<string, GlobalPluginData>;
+  export const useAllDocsData: () => {[pluginId: string]: GlobalPluginData};
   export const useDocsData: (pluginId?: string) => GlobalPluginData;
   export const useActivePlugin: (
-    options?: GetActivePluginOptions,
+    options?: UseDataOptions,
   ) => ActivePlugin | undefined;
   export const useActivePluginAndVersion: (
-    options?: GetActivePluginOptions,
+    options?: UseDataOptions,
   ) =>
     | {activePlugin: ActivePlugin; activeVersion: GlobalVersion | undefined}
     | undefined;
+  /** Versions are returned ordered (most recent first). */
   export const useVersions: (pluginId?: string) => GlobalVersion[];
   export const useLatestVersion: (pluginId?: string) => GlobalVersion;
+  /**
+   * Returns `undefined` on doc-unrelated pages, because there's no version
+   * currently considered as active.
+   */
   export const useActiveVersion: (
     pluginId?: string,
   ) => GlobalVersion | undefined;
   export const useActiveDocContext: (pluginId?: string) => ActiveDocContext;
+  /**
+   * Useful to say "hey, you are not on the latest docs version, please switch"
+   */
   export const useDocVersionSuggestions: (
     pluginId?: string,
   ) => DocVersionSuggestions;