@docusaurus/theme-common 2.0.0-beta.18 → 2.0.0-beta.19

package/src/utils/codeBlockUtils.ts

@@ -6,64 +6,89 @@
  */
 
 import rangeParser from 'parse-numeric-range';
+import type {PrismTheme} from 'prism-react-renderer';
+import type {CSSProperties} from 'react';
 
 const codeBlockTitleRegex = /title=(?<quote>["'])(?<title>.*?)\1/;
-const highlightLinesRangeRegex = /\{(?<range>[\d,-]+)\}/;
+const metastringLinesRangeRegex = /\{(?<range>[\d,-]+)\}/;
 
 // Supported types of highlight comments
 const commentPatterns = {
   js: {start: '\\/\\/', end: ''},
   jsBlock: {start: '\\/\\*', end: '\\*\\/'},
   jsx: {start: '\\{\\s*\\/\\*', end: '\\*\\/\\s*\\}'},
-  python: {start: '#', end: ''},
+  bash: {start: '#', end: ''},
   html: {start: '<!--', end: '-->'},
 };
 
 type CommentType = keyof typeof commentPatterns;
 
-const magicCommentDirectives = [
-  'highlight-next-line',
-  'highlight-start',
-  'highlight-end',
-];
+export type MagicCommentConfig = {
+  className: string;
+  line?: string;
+  block?: {start: string; end: string};
+};
 
-function getCommentPattern(languages: CommentType[]) {
-  // to be more reliable, the opening and closing comment must match
+function getCommentPattern(
+  languages: CommentType[],
+  magicCommentDirectives: MagicCommentConfig[],
+) {
+  // To be more reliable, the opening and closing comment must match
   const commentPattern = languages
     .map((lang) => {
       const {start, end} = commentPatterns[lang];
-      return `(?:${start}\\s*(${magicCommentDirectives.join('|')})\\s*${end})`;
+      return `(?:${start}\\s*(${magicCommentDirectives
+        .flatMap((d) => [d.line, d.block?.start, d.block?.end].filter(Boolean))
+        .join('|')})\\s*${end})`;
     })
     .join('|');
-  // white space is allowed, but otherwise it should be on it's own line
+  // White space is allowed, but otherwise it should be on it's own line
   return new RegExp(`^\\s*(?:${commentPattern})\\s*$`);
 }
 
 /**
  * Select comment styles based on language
  */
-function getAllMagicCommentDirectiveStyles(lang: string) {
+function getAllMagicCommentDirectiveStyles(
+  lang: string,
+  magicCommentDirectives: MagicCommentConfig[],
+) {
   switch (lang) {
     case 'js':
     case 'javascript':
     case 'ts':
     case 'typescript':
-      return getCommentPattern(['js', 'jsBlock']);
+      return getCommentPattern(['js', 'jsBlock'], magicCommentDirectives);
 
     case 'jsx':
     case 'tsx':
-      return getCommentPattern(['js', 'jsBlock', 'jsx']);
+      return getCommentPattern(
+        ['js', 'jsBlock', 'jsx'],
+        magicCommentDirectives,
+      );
 
     case 'html':
-      return getCommentPattern(['js', 'jsBlock', 'html']);
+      return getCommentPattern(
+        ['js', 'jsBlock', 'html'],
+        magicCommentDirectives,
+      );
 
     case 'python':
     case 'py':
-      return getCommentPattern(['python']);
+    case 'bash':
+      return getCommentPattern(['bash'], magicCommentDirectives);
+
+    case 'markdown':
+    case 'md':
+      // Text uses HTML, front matter uses bash
+      return getCommentPattern(['html', 'jsx', 'bash'], magicCommentDirectives);
 
     default:
-      // all comment types
-      return getCommentPattern(Object.keys(commentPatterns) as CommentType[]);
+      // All comment types
+      return getCommentPattern(
+        Object.keys(commentPatterns) as CommentType[],
+        magicCommentDirectives,
+      );
   }
 }
 
@@ -71,6 +96,10 @@ export function parseCodeBlockTitle(metastring?: string): string {
   return metastring?.match(codeBlockTitleRegex)?.groups!.title ?? '';
 }
 
+export function containsLineNumbers(metastring?: string): boolean {
+  return metastring?.includes('showLineNumbers') || false;
+}
+
 /**
  * Gets the language name from the class name (set by MDX).
  * e.g. `"language-javascript"` => `"javascript"`.
@@ -87,79 +116,134 @@ export function parseLanguage(className: string): string | undefined {
  * Parses the code content, strips away any magic comments, and returns the
  * clean content and the highlighted lines marked by the comments or metastring.
  *
- * If the metastring contains highlight range, the `content` will be returned
- * as-is without any parsing.
+ * If the metastring contains a range, the `content` will be returned as-is
+ * without any parsing. The returned `lineClassNames` will be a map from that
+ * number range to the first magic comment config entry (which _should_ be for
+ * line highlight directives.)
  *
  * @param content The raw code with magic comments. Trailing newline will be
  * trimmed upfront.
- * @param metastring The full metastring, as received from MDX. Highlight range
- * declared here starts at 1.
- * @param language Language of the code block, used to determine which kinds of
- * magic comment styles to enable.
+ * @param options Options for parsing behavior.
  */
 export function parseLines(
   content: string,
-  metastring?: string,
-  language?: string,
+  options: {
+    /**
+     * The full metastring, as received from MDX. Line ranges declared here
+     * start at 1.
+     */
+    metastring: string | undefined;
+    /**
+     * Language of the code block, used to determine which kinds of magic
+     * comment styles to enable.
+     */
+    language: string | undefined;
+    /**
+     * Magic comment types that we should try to parse. Each entry would
+     * correspond to one class name to apply to each line.
+     */
+    magicComments: MagicCommentConfig[];
+  },
 ): {
   /**
-   * The highlighted lines, 0-indexed. e.g. `[0, 1, 4]` means the 1st, 2nd, and
-   * 5th lines are highlighted.
+   * The highlighted lines, 0-indexed. e.g. `{ 0: ["highlight", "sample"] }`
+   * means the 1st line should have `highlight` and `sample` as class names.
    */
-  highlightLines: number[];
+  lineClassNames: {[lineIndex: number]: string[]};
   /**
-   * The clean code without any magic comments (only if highlight range isn't
-   * present in the metastring).
+   * If there's number range declared in the metastring, the code block is
+   * returned as-is (no parsing); otherwise, this is the clean code with all
+   * magic comments stripped away.
    */
   code: string;
 } {
   let code = content.replace(/\n$/, '');
+  const {language, magicComments, metastring} = options;
   // Highlighted lines specified in props: don't parse the content
-  if (metastring && highlightLinesRangeRegex.test(metastring)) {
-    const highlightLinesRange = metastring.match(highlightLinesRangeRegex)!
-      .groups!.range!;
-    const highlightLines = rangeParser(highlightLinesRange)
+  if (metastring && metastringLinesRangeRegex.test(metastring)) {
+    const linesRange = metastring.match(metastringLinesRangeRegex)!.groups!
+      .range!;
+    if (magicComments.length === 0) {
+      throw new Error(
+        `A highlight range has been given in code block's metastring (\`\`\` ${metastring}), but no magic comment config is available. Docusaurus applies the first magic comment entry's className for metastring ranges.`,
+      );
+    }
+    const metastringRangeClassName = magicComments[0]!.className;
+    const lines = rangeParser(linesRange)
       .filter((n) => n > 0)
-      .map((n) => n - 1);
-    return {highlightLines, code};
+      .map((n) => [n - 1, [metastringRangeClassName]]);
+    return {lineClassNames: Object.fromEntries(lines), code};
   }
   if (language === undefined) {
-    return {highlightLines: [], code};
+    return {lineClassNames: {}, code};
   }
-  const directiveRegex = getAllMagicCommentDirectiveStyles(language);
-  // go through line by line
+  const directiveRegex = getAllMagicCommentDirectiveStyles(
+    language,
+    magicComments,
+  );
+  // Go through line by line
   const lines = code.split('\n');
-  let highlightBlockStart: number;
-  let highlightRange = '';
-  // loop through lines
+  const blocks = Object.fromEntries(
+    magicComments.map((d) => [d.className, {start: 0, range: ''}]),
+  );
+  const lineToClassName: {[comment: string]: string} = Object.fromEntries(
+    magicComments
+      .filter((d) => d.line)
+      .map(({className, line}) => [line, className]),
+  );
+  const blockStartToClassName: {[comment: string]: string} = Object.fromEntries(
+    magicComments
+      .filter((d) => d.block)
+      .map(({className, block}) => [block!.start, className]),
+  );
+  const blockEndToClassName: {[comment: string]: string} = Object.fromEntries(
+    magicComments
+      .filter((d) => d.block)
+      .map(({className, block}) => [block!.end, className]),
+  );
   for (let lineNumber = 0; lineNumber < lines.length; ) {
     const line = lines[lineNumber]!;
     const match = line.match(directiveRegex);
-    if (match !== null) {
-      const directive = match.slice(1).find((item) => item !== undefined);
-      switch (directive) {
-        case 'highlight-next-line':
-          highlightRange += `${lineNumber},`;
-          break;
-
-        case 'highlight-start':
-          highlightBlockStart = lineNumber;
-          break;
-
-        case 'highlight-end':
-          highlightRange += `${highlightBlockStart!}-${lineNumber - 1},`;
-          break;
-
-        default:
-          break;
-      }
-      lines.splice(lineNumber, 1);
-    } else {
-      // lines without directives are unchanged
+    if (!match) {
+      // Lines without directives are unchanged
       lineNumber += 1;
+      continue;
     }
+    const directive = match.slice(1).find((item) => item !== undefined)!;
+    if (lineToClassName[directive]) {
+      blocks[lineToClassName[directive]!]!.range += `${lineNumber},`;
+    } else if (blockStartToClassName[directive]) {
+      blocks[blockStartToClassName[directive]!]!.start = lineNumber;
+    } else if (blockEndToClassName[directive]) {
+      blocks[blockEndToClassName[directive]!]!.range += `${
+        blocks[blockEndToClassName[directive]!]!.start
+      }-${lineNumber - 1},`;
+    }
+    lines.splice(lineNumber, 1);
   }
-  const highlightLines = rangeParser(highlightRange);
   code = lines.join('\n');
-  return {highlightLines, code};
+  const lineClassNames: {[lineIndex: number]: string[]} = {};
+  Object.entries(blocks).forEach(([className, {range}]) => {
+    rangeParser(range).forEach((l) => {
+      lineClassNames[l] ??= [];
+      lineClassNames[l]!.push(className);
+    });
+  });
+  return {lineClassNames, code};
+}
+
+export function getPrismCssVariables(prismTheme: PrismTheme): CSSProperties {
+  const mapping: {[name: keyof PrismTheme['plain']]: string} = {
+    color: '--prism-color',
+    backgroundColor: '--prism-background-color',
+  };
+
+  const properties: {[key: string]: string} = {};
+  Object.entries(prismTheme.plain).forEach(([key, value]) => {
+    const varName = mapping[key];
+    if (varName && typeof value === 'string') {
+      properties[varName] = value;
+    }
+  });
+  return properties;
 }

package/src/utils/docsUtils.tsx

@@ -5,9 +5,15 @@
  * LICENSE file in the root directory of this source tree.
  */
 
+import {useMemo} from 'react';
 import {
   useAllDocsData,
   useActivePlugin,
+  useActiveDocContext,
+  useLatestVersion,
+  type GlobalVersion,
+  type GlobalSidebar,
+  type GlobalDoc,
 } from '@docusaurus/plugin-content-docs/client';
 import type {
   PropSidebar,
@@ -16,10 +22,14 @@ import type {
   PropVersionDoc,
   PropSidebarBreadcrumbsItem,
 } from '@docusaurus/plugin-content-docs';
+import type {Props as DocPageProps} from '@theme/DocPage';
+import {useDocsPreferredVersion} from '../contexts/docsPreferredVersion';
 import {useDocsVersion} from '../contexts/docsVersion';
 import {useDocsSidebar} from '../contexts/docsSidebar';
+import {uniq} from './jsUtils';
 import {isSamePath} from './routesUtils';
-import {useLocation} from '@docusaurus/router';
+import {matchPath, useLocation} from '@docusaurus/router';
+import renderRoutes from '@docusaurus/renderRoutes';
 
 // TODO not ideal, see also "useDocs"
 export const isDocsPluginEnabled: boolean = !!useAllDocsData;
@@ -84,13 +94,8 @@ export function findFirstCategoryLink(
       if (categoryLink) {
         return categoryLink;
       }
-    } else if (subItem.type === 'html') {
-      // skip
-    } else {
-      throw new Error(
-        `Unexpected category item type for ${JSON.stringify(subItem)}`,
-      );
     }
+    // Could be "html" items
   }
   return undefined;
 }
@@ -105,7 +110,7 @@ export function useCurrentSidebarCategory(): PropSidebarItemCategory {
   if (!sidebar) {
     throw new Error('Unexpected: cant find current sidebar in context');
   }
-  const category = findSidebarCategory(sidebar, (item) =>
+  const category = findSidebarCategory(sidebar.items, (item) =>
     isSamePath(item.href, pathname),
   );
   if (!category) {
@@ -174,7 +179,156 @@ export function useSidebarBreadcrumbs(): PropSidebarBreadcrumbsItem[] | null {
     return false;
   }
 
-  extract(sidebar);
+  extract(sidebar.items);
 
   return breadcrumbs.reverse();
 }
+
+/**
+ * "Version candidates" are mostly useful for the layout components, which must
+ * be able to work on all pages. For example, if a user has `{ type: "doc",
+ * docId: "intro" }` as a navbar item, which version does that refer to? We
+ * believe that it could refer to at most three version candidates:
+ *
+ * 1. The **active version**, the one that the user is currently browsing. See
+ * {@link useActiveDocContext}.
+ * 2. The **preferred version**, the one that the user last visited. See
+ * {@link useDocsPreferredVersion}.
+ * 3. The **latest version**, the "default". See {@link useLatestVersion}.
+ *
+ * @param docsPluginId The plugin ID to get versions from.
+ * @returns An array of 1~3 versions with priorities defined above, guaranteed
+ * to be unique and non-sparse. Will be memoized, hence stable for deps array.
+ */
+export function useDocsVersionCandidates(
+  docsPluginId?: string,
+): [GlobalVersion, ...GlobalVersion[]] {
+  const {activeVersion} = useActiveDocContext(docsPluginId);
+  const {preferredVersion} = useDocsPreferredVersion(docsPluginId);
+  const latestVersion = useLatestVersion(docsPluginId);
+  return useMemo(
+    () =>
+      uniq(
+        [activeVersion, preferredVersion, latestVersion].filter(Boolean),
+      ) as [GlobalVersion, ...GlobalVersion[]],
+    [activeVersion, preferredVersion, latestVersion],
+  );
+}
+
+/**
+ * The layout components, like navbar items, must be able to work on all pages,
+ * even on non-doc ones where there's no version context, so a sidebar ID could
+ * be ambiguous. This hook would always return a sidebar to be linked to. See
+ * also {@link useDocsVersionCandidates} for how this selection is done.
+ *
+ * @throws This hook throws if a sidebar with said ID is not found.
+ */
+export function useLayoutDocsSidebar(
+  sidebarId: string,
+  docsPluginId?: string,
+): GlobalSidebar {
+  const versions = useDocsVersionCandidates(docsPluginId);
+  return useMemo(() => {
+    const allSidebars = versions.flatMap((version) =>
+      version.sidebars ? Object.entries(version.sidebars) : [],
+    );
+    const sidebarEntry = allSidebars.find(
+      (sidebar) => sidebar[0] === sidebarId,
+    );
+    if (!sidebarEntry) {
+      throw new Error(
+        `Can't find any sidebar with id "${sidebarId}" in version${
+          versions.length > 1 ? 's' : ''
+        } ${versions.map((version) => version.name).join(', ')}".
+  Available sidebar ids are:
+  - ${Object.keys(allSidebars).join('\n- ')}`,
+      );
+    }
+    return sidebarEntry[1];
+  }, [sidebarId, versions]);
+}
+
+/**
+ * The layout components, like navbar items, must be able to work on all pages,
+ * even on non-doc ones where there's no version context, so a doc ID could be
+ * ambiguous. This hook would always return a doc to be linked to. See also
+ * {@link useDocsVersionCandidates} for how this selection is done.
+ *
+ * @throws This hook throws if a doc with said ID is not found.
+ */
+export function useLayoutDoc(
+  docId: string,
+  docsPluginId?: string,
+): GlobalDoc | null {
+  const versions = useDocsVersionCandidates(docsPluginId);
+  return useMemo(() => {
+    const allDocs = versions.flatMap((version) => version.docs);
+    const doc = allDocs.find((versionDoc) => versionDoc.id === docId);
+    if (!doc) {
+      const isDraft = versions
+        .flatMap((version) => version.draftIds)
+        .includes(docId);
+      // Drafts should be silently filtered instead of throwing
+      if (isDraft) {
+        return null;
+      }
+      throw new Error(
+        `DocNavbarItem: couldn't find any doc with id "${docId}" in version${
+          versions.length > 1 ? 's' : ''
+        } ${versions.map((version) => version.name).join(', ')}".
+Available doc ids are:
+- ${uniq(allDocs.map((versionDoc) => versionDoc.id)).join('\n- ')}`,
+      );
+    }
+    return doc;
+  }, [docId, versions]);
+}
+
+// TODO later read version/route directly from context
+/**
+ * The docs plugin creates nested routes, with the top-level route providing the
+ * version metadata, and the subroutes creating individual doc pages. This hook
+ * will match the current location against all known sub-routes.
+ *
+ * @param props The props received by `@theme/DocPage`
+ * @returns The data of the relevant document at the current location, or `null`
+ * if no document associated with the current location can be found.
+ */
+export function useDocRouteMetadata({
+  route,
+  versionMetadata,
+}: DocPageProps): null | {
+  /** The element that should be rendered at the current location. */
+  docElement: JSX.Element;
+  /**
+   * The name of the sidebar associated with the current doc. `sidebarName` and
+   * `sidebarItems` correspond to the value of {@link useDocsSidebar}.
+   */
+  sidebarName: string | undefined;
+  /** The items of the sidebar associated with the current doc. */
+  sidebarItems: PropSidebar | undefined;
+} {
+  const location = useLocation();
+  const docRoutes = route.routes!;
+  const currentDocRoute = docRoutes.find((docRoute) =>
+    matchPath(location.pathname, docRoute),
+  );
+  if (!currentDocRoute) {
+    return null;
+  }
+
+  // For now, the sidebarName is added as route config: not ideal!
+  const sidebarName = currentDocRoute.sidebar;
+
+  const sidebarItems = sidebarName
+    ? versionMetadata.docsSidebars[sidebarName]
+    : undefined;
+
+  const docElement = renderRoutes(docRoutes, {versionMetadata});
+
+  return {
+    docElement,
+    sidebarName,
+    sidebarItems,
+  };
+}

package/src/utils/metadataUtils.tsx

@@ -12,13 +12,13 @@ import useRouteContext from '@docusaurus/useRouteContext';
 import {useBaseUrlUtils} from '@docusaurus/useBaseUrl';
 import {useTitleFormatter} from './generalUtils';
 
-interface PageMetadataProps {
+type PageMetadataProps = {
   readonly title?: string;
   readonly description?: string;
   readonly keywords?: readonly string[] | string;
   readonly image?: string;
   readonly children?: ReactNode;
-}
+};
 
 /**
  * Helper component to manipulate page metadata and override site defaults.

package/src/utils/navbarUtils.tsx

@@ -7,7 +7,8 @@
 
 import React, {type ReactNode} from 'react';
 import {NavbarMobileSidebarProvider} from '../contexts/navbarMobileSidebar';
-import {NavbarSecondaryMenuProvider} from '../contexts/navbarSecondaryMenu';
+import {NavbarSecondaryMenuContentProvider} from '../contexts/navbarSecondaryMenu/content';
+import {NavbarSecondaryMenuDisplayProvider} from '../contexts/navbarSecondaryMenu/display';
 
 const DefaultNavItemPosition = 'right';
 
@@ -28,13 +29,17 @@ export function splitNavbarItems<T extends {position?: 'left' | 'right'}>(
 }
 
 /**
- * Composes the `NavbarMobileSidebarProvider` and `NavbarSecondaryMenuProvider`.
- * Because the latter depends on the former, they can't be re-ordered.
+ * Composes multiple navbar state providers that are mutually dependent and
+ * hence can't be re-ordered.
  */
 export function NavbarProvider({children}: {children: ReactNode}): JSX.Element {
   return (
-    <NavbarMobileSidebarProvider>
-      <NavbarSecondaryMenuProvider>{children}</NavbarSecondaryMenuProvider>
-    </NavbarMobileSidebarProvider>
+    <NavbarSecondaryMenuContentProvider>
+      <NavbarMobileSidebarProvider>
+        <NavbarSecondaryMenuDisplayProvider>
+          {children}
+        </NavbarSecondaryMenuDisplayProvider>
+      </NavbarMobileSidebarProvider>
+    </NavbarSecondaryMenuContentProvider>
   );
 }

package/src/utils/routesUtils.ts

@@ -8,7 +8,7 @@
 import {useMemo} from 'react';
 import generatedRoutes from '@generated/routes';
 import useDocusaurusContext from '@docusaurus/useDocusaurusContext';
-import type {Route} from '@docusaurus/types';
+import type {RouteConfig} from 'react-router-config';
 
 /**
  * Compare the 2 paths, case insensitive and ignoring trailing slash
@@ -34,18 +34,18 @@ export function findHomePageRoute({
   baseUrl,
   routes: initialRoutes,
 }: {
-  routes: Route[];
+  routes: RouteConfig[];
   baseUrl: string;
-}): Route | undefined {
-  function isHomePageRoute(route: Route): boolean {
+}): RouteConfig | undefined {
+  function isHomePageRoute(route: RouteConfig): boolean {
     return route.path === baseUrl && route.exact === true;
   }
 
-  function isHomeParentRoute(route: Route): boolean {
+  function isHomeParentRoute(route: RouteConfig): boolean {
     return route.path === baseUrl && !route.exact;
   }
 
-  function doFindHomePageRoute(routes: Route[]): Route | undefined {
+  function doFindHomePageRoute(routes: RouteConfig[]): RouteConfig | undefined {
     if (routes.length === 0) {
       return undefined;
     }
@@ -66,7 +66,7 @@ export function findHomePageRoute({
  * Fetches the route that points to "/". Use this instead of the naive "/",
  * because the homepage may not exist.
  */
-export function useHomePageRoute(): Route | undefined {
+export function useHomePageRoute(): RouteConfig | undefined {
   const {baseUrl} = useDocusaurusContext().siteConfig;
   return useMemo(
     () => findHomePageRoute({routes: generatedRoutes, baseUrl}),