@docusaurus/theme-common 2.0.0-beta.1decd6f80 → 2.0.0-beta.20

package/lib/utils/ThemeClassNames.d.ts

@@ -4,19 +4,54 @@
  * This source code is licensed under the MIT license found in the
  * LICENSE file in the root directory of this source tree.
  */
+/**
+ * These class names are used to style page layouts in Docusaurus, meant to be
+ * targeted by user-provided custom CSS selectors.
+ */
 export declare const ThemeClassNames: {
-    page: {
-        blogListPage: string;
-        blogPostPage: string;
-        blogTagsListPage: string;
-        blogTagsPostPage: string;
-        docPage: string;
-        mdxPage: string;
+    readonly page: {
+        readonly blogListPage: "blog-list-page";
+        readonly blogPostPage: "blog-post-page";
+        readonly blogTagsListPage: "blog-tags-list-page";
+        readonly blogTagPostListPage: "blog-tags-post-list-page";
+        readonly docsDocPage: "docs-doc-page";
+        readonly docsTagsListPage: "docs-tags-list-page";
+        readonly docsTagDocListPage: "docs-tags-doc-list-page";
+        readonly mdxPage: "mdx-page";
+    };
+    readonly wrapper: {
+        readonly main: "main-wrapper";
+        readonly blogPages: "blog-wrapper";
+        readonly docsPages: "docs-wrapper";
+        readonly mdxPages: "mdx-wrapper";
+    };
+    /**
+     * Follows the naming convention "theme-{blog,doc,version,page}?-<suffix>"
+     */
+    readonly common: {
+        readonly editThisPage: "theme-edit-this-page";
+        readonly lastUpdated: "theme-last-updated";
+        readonly backToTopButton: "theme-back-to-top-button";
+        readonly codeBlock: "theme-code-block";
     };
-    wrapper: {
-        main: string;
-        blogPages: string;
-        docPages: string;
-        mdxPages: string;
+    readonly layout: {};
+    readonly docs: {
+        readonly docVersionBanner: "theme-doc-version-banner";
+        readonly docVersionBadge: "theme-doc-version-badge";
+        readonly docBreadcrumbs: "theme-doc-breadcrumbs";
+        readonly docMarkdown: "theme-doc-markdown";
+        readonly docTocMobile: "theme-doc-toc-mobile";
+        readonly docTocDesktop: "theme-doc-toc-desktop";
+        readonly docFooter: "theme-doc-footer";
+        readonly docFooterTagsRow: "theme-doc-footer-tags-row";
+        readonly docFooterEditMetaRow: "theme-doc-footer-edit-meta-row";
+        readonly docSidebarContainer: "theme-doc-sidebar-container";
+        readonly docSidebarMenu: "theme-doc-sidebar-menu";
+        readonly docSidebarItemCategory: "theme-doc-sidebar-item-category";
+        readonly docSidebarItemLink: "theme-doc-sidebar-item-link";
+        readonly docSidebarItemCategoryLevel: (level: number) => `theme-doc-sidebar-item-category-level-${number}`;
+        readonly docSidebarItemLinkLevel: (level: number) => `theme-doc-sidebar-item-link-level-${number}`;
     };
+    readonly blog: {};
 };
+//# sourceMappingURL=ThemeClassNames.d.ts.map

package/lib/utils/ThemeClassNames.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"ThemeClassNames.d.ts","sourceRoot":"","sources":["../../src/utils/ThemeClassNames.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAKH;;;GAGG;AACH,eAAO,MAAM,eAAe;;;;;;;;;;;;;;;;;IAoB1B;;OAEG;;;;;;;;;;;;;;;;;;;;;;sDAwBoC,MAAM;kDAEV,MAAM;;;CAOjC,CAAC"}

package/lib/utils/ThemeClassNames.js

@@ -4,20 +4,61 @@
  * This source code is licensed under the MIT license found in the
  * LICENSE file in the root directory of this source tree.
  */
-// These class names are used to style page layouts in Docusaurus
+// Please do not modify the classnames! This is a breaking change, and annoying
+// for users!
+/**
+ * These class names are used to style page layouts in Docusaurus, meant to be
+ * targeted by user-provided custom CSS selectors.
+ */
 export const ThemeClassNames = {
     page: {
         blogListPage: 'blog-list-page',
         blogPostPage: 'blog-post-page',
         blogTagsListPage: 'blog-tags-list-page',
-        blogTagsPostPage: 'blog-tags-post-page',
-        docPage: 'doc-page',
+        blogTagPostListPage: 'blog-tags-post-list-page',
+        docsDocPage: 'docs-doc-page',
+        docsTagsListPage: 'docs-tags-list-page',
+        docsTagDocListPage: 'docs-tags-doc-list-page',
         mdxPage: 'mdx-page',
     },
     wrapper: {
         main: 'main-wrapper',
         blogPages: 'blog-wrapper',
-        docPages: 'docs-wrapper',
+        docsPages: 'docs-wrapper',
         mdxPages: 'mdx-wrapper',
     },
+    /**
+     * Follows the naming convention "theme-{blog,doc,version,page}?-<suffix>"
+     */
+    common: {
+        editThisPage: 'theme-edit-this-page',
+        lastUpdated: 'theme-last-updated',
+        backToTopButton: 'theme-back-to-top-button',
+        codeBlock: 'theme-code-block',
+    },
+    layout: {
+    // TODO add other stable classNames here
+    },
+    docs: {
+        docVersionBanner: 'theme-doc-version-banner',
+        docVersionBadge: 'theme-doc-version-badge',
+        docBreadcrumbs: 'theme-doc-breadcrumbs',
+        docMarkdown: 'theme-doc-markdown',
+        docTocMobile: 'theme-doc-toc-mobile',
+        docTocDesktop: 'theme-doc-toc-desktop',
+        docFooter: 'theme-doc-footer',
+        docFooterTagsRow: 'theme-doc-footer-tags-row',
+        docFooterEditMetaRow: 'theme-doc-footer-edit-meta-row',
+        docSidebarContainer: 'theme-doc-sidebar-container',
+        docSidebarMenu: 'theme-doc-sidebar-menu',
+        docSidebarItemCategory: 'theme-doc-sidebar-item-category',
+        docSidebarItemLink: 'theme-doc-sidebar-item-link',
+        docSidebarItemCategoryLevel: (level) => `theme-doc-sidebar-item-category-level-${level}`,
+        docSidebarItemLinkLevel: (level) => `theme-doc-sidebar-item-link-level-${level}`,
+        // TODO add other stable classNames here
+    },
+    blog: {
+    // TODO add other stable classNames here
+    },
 };
+//# sourceMappingURL=ThemeClassNames.js.map

package/lib/utils/ThemeClassNames.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"ThemeClassNames.js","sourceRoot":"","sources":["../../src/utils/ThemeClassNames.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAEH,+EAA+E;AAC/E,aAAa;AAEb;;;GAGG;AACH,MAAM,CAAC,MAAM,eAAe,GAAG;IAC7B,IAAI,EAAE;QACJ,YAAY,EAAE,gBAAgB;QAC9B,YAAY,EAAE,gBAAgB;QAC9B,gBAAgB,EAAE,qBAAqB;QACvC,mBAAmB,EAAE,0BAA0B;QAE/C,WAAW,EAAE,eAAe;QAC5B,gBAAgB,EAAE,qBAAqB;QACvC,kBAAkB,EAAE,yBAAyB;QAE7C,OAAO,EAAE,UAAU;KACpB;IACD,OAAO,EAAE;QACP,IAAI,EAAE,cAAc;QACpB,SAAS,EAAE,cAAc;QACzB,SAAS,EAAE,cAAc;QACzB,QAAQ,EAAE,aAAa;KACxB;IAED;;OAEG;IACH,MAAM,EAAE;QACN,YAAY,EAAE,sBAAsB;QACpC,WAAW,EAAE,oBAAoB;QACjC,eAAe,EAAE,0BAA0B;QAC3C,SAAS,EAAE,kBAAkB;KAC9B;IACD,MAAM,EAAE;IACN,wCAAwC;KACzC;IACD,IAAI,EAAE;QACJ,gBAAgB,EAAE,0BAA0B;QAC5C,eAAe,EAAE,yBAAyB;QAC1C,cAAc,EAAE,uBAAuB;QACvC,WAAW,EAAE,oBAAoB;QACjC,YAAY,EAAE,sBAAsB;QACpC,aAAa,EAAE,uBAAuB;QACtC,SAAS,EAAE,kBAAkB;QAC7B,gBAAgB,EAAE,2BAA2B;QAC7C,oBAAoB,EAAE,gCAAgC;QACtD,mBAAmB,EAAE,6BAA6B;QAClD,cAAc,EAAE,wBAAwB;QACxC,sBAAsB,EAAE,iCAAiC;QACzD,kBAAkB,EAAE,6BAA6B;QACjD,2BAA2B,EAAE,CAAC,KAAa,EAAE,EAAE,CAC7C,yCAAyC,KAAK,EAAW;QAC3D,uBAAuB,EAAE,CAAC,KAAa,EAAE,EAAE,CACzC,qCAAqC,KAAK,EAAW;QACvD,wCAAwC;KACzC;IACD,IAAI,EAAE;IACJ,wCAAwC;KACzC;CACO,CAAC"}

package/lib/utils/codeBlockUtils.d.ts

@@ -4,4 +4,67 @@
  * This source code is licensed under the MIT license found in the
  * LICENSE file in the root directory of this source tree.
  */
+import type { PrismTheme } from 'prism-react-renderer';
+import type { CSSProperties } from 'react';
+export declare type MagicCommentConfig = {
+    className: string;
+    line?: string;
+    block?: {
+        start: string;
+        end: string;
+    };
+};
 export declare function parseCodeBlockTitle(metastring?: string): string;
+export declare function containsLineNumbers(metastring?: string): boolean;
+/**
+ * Gets the language name from the class name (set by MDX).
+ * e.g. `"language-javascript"` => `"javascript"`.
+ * Returns undefined if there is no language class name.
+ */
+export declare 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 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 options Options for parsing behavior.
+ */
+export declare function parseLines(content: 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: ["highlight", "sample"] }`
+     * means the 1st line should have `highlight` and `sample` as class names.
+     */
+    lineClassNames: {
+        [lineIndex: number]: string[];
+    };
+    /**
+     * 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;
+};
+export declare function getPrismCssVariables(prismTheme: PrismTheme): CSSProperties;
+//# sourceMappingURL=codeBlockUtils.d.ts.map

package/lib/utils/codeBlockUtils.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"codeBlockUtils.d.ts","sourceRoot":"","sources":["../../src/utils/codeBlockUtils.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAGH,OAAO,KAAK,EAAC,UAAU,EAAC,MAAM,sBAAsB,CAAC;AACrD,OAAO,KAAK,EAAC,aAAa,EAAC,MAAM,OAAO,CAAC;AAgBzC,oBAAY,kBAAkB,GAAG;IAC/B,SAAS,EAAE,MAAM,CAAC;IAClB,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,KAAK,CAAC,EAAE;QAAC,KAAK,EAAE,MAAM,CAAC;QAAC,GAAG,EAAE,MAAM,CAAA;KAAC,CAAC;CACtC,CAAC;AAiEF,wBAAgB,mBAAmB,CAAC,UAAU,CAAC,EAAE,MAAM,GAAG,MAAM,CAE/D;AAED,wBAAgB,mBAAmB,CAAC,UAAU,CAAC,EAAE,MAAM,GAAG,OAAO,CAEhE;AAED;;;;GAIG;AACH,wBAAgB,aAAa,CAAC,SAAS,EAAE,MAAM,GAAG,MAAM,GAAG,SAAS,CAKnE;AAED;;;;;;;;;;;;GAYG;AACH,wBAAgB,UAAU,CACxB,OAAO,EAAE,MAAM,EACf,OAAO,EAAE;IACP;;;OAGG;IACH,UAAU,EAAE,MAAM,GAAG,SAAS,CAAC;IAC/B;;;OAGG;IACH,QAAQ,EAAE,MAAM,GAAG,SAAS,CAAC;IAC7B;;;OAGG;IACH,aAAa,EAAE,kBAAkB,EAAE,CAAC;CACrC,GACA;IACD;;;OAGG;IACH,cAAc,EAAE;QAAC,CAAC,SAAS,EAAE,MAAM,GAAG,MAAM,EAAE,CAAA;KAAC,CAAC;IAChD;;;;OAIG;IACH,IAAI,EAAE,MAAM,CAAC;CACd,CA0EA;AAED,wBAAgB,oBAAoB,CAAC,UAAU,EAAE,UAAU,GAAG,aAAa,CAc1E"}

package/lib/utils/codeBlockUtils.js

@@ -4,8 +4,162 @@
  * This source code is licensed under the MIT license found in the
  * LICENSE file in the root directory of this source tree.
  */
-const codeBlockTitleRegex = /title=(["'])(.*?)\1/;
+import rangeParser from 'parse-numeric-range';
+const codeBlockTitleRegex = /title=(?<quote>["'])(?<title>.*?)\1/;
+const metastringLinesRangeRegex = /\{(?<range>[\d,-]+)\}/;
+// Supported types of highlight comments
+const commentPatterns = {
+    js: { start: '\\/\\/', end: '' },
+    jsBlock: { start: '\\/\\*', end: '\\*\\/' },
+    jsx: { start: '\\{\\s*\\/\\*', end: '\\*\\/\\s*\\}' },
+    bash: { start: '#', end: '' },
+    html: { start: '<!--', end: '-->' },
+};
+function getCommentPattern(languages, magicCommentDirectives) {
+    // 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
+            .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
+    return new RegExp(`^\\s*(?:${commentPattern})\\s*$`);
+}
+/**
+ * Select comment styles based on language
+ */
+function getAllMagicCommentDirectiveStyles(lang, magicCommentDirectives) {
+    switch (lang) {
+        case 'js':
+        case 'javascript':
+        case 'ts':
+        case 'typescript':
+            return getCommentPattern(['js', 'jsBlock'], magicCommentDirectives);
+        case 'jsx':
+        case 'tsx':
+            return getCommentPattern(['js', 'jsBlock', 'jsx'], magicCommentDirectives);
+        case 'html':
+            return getCommentPattern(['js', 'jsBlock', 'html'], magicCommentDirectives);
+        case 'python':
+        case 'py':
+        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), magicCommentDirectives);
+    }
+}
 export function parseCodeBlockTitle(metastring) {
-    var _a, _b;
-    return (_b = (_a = metastring === null || metastring === void 0 ? void 0 : metastring.match(codeBlockTitleRegex)) === null || _a === void 0 ? void 0 : _a[2]) !== null && _b !== void 0 ? _b : '';
+    return metastring?.match(codeBlockTitleRegex)?.groups.title ?? '';
+}
+export function containsLineNumbers(metastring) {
+    return metastring?.includes('showLineNumbers') || false;
+}
+/**
+ * Gets the language name from the class name (set by MDX).
+ * e.g. `"language-javascript"` => `"javascript"`.
+ * Returns undefined if there is no language class name.
+ */
+export function parseLanguage(className) {
+    const languageClassName = className
+        .split(' ')
+        .find((str) => str.startsWith('language-'));
+    return languageClassName?.replace(/language-/, '');
+}
+/**
+ * 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 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 options Options for parsing behavior.
+ */
+export function parseLines(content, options) {
+    let code = content.replace(/\n$/, '');
+    const { language, magicComments, metastring } = options;
+    // Highlighted lines specified in props: don't parse the content
+    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, [metastringRangeClassName]]);
+        return { lineClassNames: Object.fromEntries(lines), code };
+    }
+    if (language === undefined) {
+        return { lineClassNames: {}, code };
+    }
+    const directiveRegex = getAllMagicCommentDirectiveStyles(language, magicComments);
+    // Go through line by line
+    const lines = code.split('\n');
+    const blocks = Object.fromEntries(magicComments.map((d) => [d.className, { start: 0, range: '' }]));
+    const lineToClassName = Object.fromEntries(magicComments
+        .filter((d) => d.line)
+        .map(({ className, line }) => [line, className]));
+    const blockStartToClassName = Object.fromEntries(magicComments
+        .filter((d) => d.block)
+        .map(({ className, block }) => [block.start, className]));
+    const blockEndToClassName = 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) {
+            // 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);
+    }
+    code = lines.join('\n');
+    const lineClassNames = {};
+    Object.entries(blocks).forEach(([className, { range }]) => {
+        rangeParser(range).forEach((l) => {
+            lineClassNames[l] ?? (lineClassNames[l] = []);
+            lineClassNames[l].push(className);
+        });
+    });
+    return { lineClassNames, code };
+}
+export function getPrismCssVariables(prismTheme) {
+    const mapping = {
+        color: '--prism-color',
+        backgroundColor: '--prism-background-color',
+    };
+    const properties = {};
+    Object.entries(prismTheme.plain).forEach(([key, value]) => {
+        const varName = mapping[key];
+        if (varName && typeof value === 'string') {
+            properties[varName] = value;
+        }
+    });
+    return properties;
 }
+//# sourceMappingURL=codeBlockUtils.js.map

package/lib/utils/codeBlockUtils.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"codeBlockUtils.js","sourceRoot":"","sources":["../../src/utils/codeBlockUtils.ts"],"names":[],"mappings":"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"}

package/lib/utils/docsUtils.d.ts

@@ -4,4 +4,95 @@
  * This source code is licensed under the MIT license found in the
  * LICENSE file in the root directory of this source tree.
  */
+/// <reference types="react" />
+import { type GlobalVersion, type GlobalSidebar, type GlobalDoc } from '@docusaurus/plugin-content-docs/client';
+import type { PropSidebar, PropSidebarItem, PropSidebarItemCategory, PropVersionDoc, PropSidebarBreadcrumbsItem } from '@docusaurus/plugin-content-docs';
+import type { Props as DocPageProps } from '@theme/DocPage';
 export declare const isDocsPluginEnabled: boolean;
+/**
+ * A null-safe way to access a doc's data by ID in the active version.
+ */
+export declare function useDocById(id: string): PropVersionDoc;
+/**
+ * A null-safe way to access a doc's data by ID in the active version.
+ */
+export declare function useDocById(id: string | undefined): PropVersionDoc | undefined;
+/**
+ * Pure function, similar to `Array#find`, but works on the sidebar tree.
+ */
+export declare function findSidebarCategory(sidebar: PropSidebar, predicate: (category: PropSidebarItemCategory) => boolean): PropSidebarItemCategory | undefined;
+/**
+ * Best effort to assign a link to a sidebar category. If the category doesn't
+ * have a link itself, we link to the first sub item with a link.
+ */
+export declare function findFirstCategoryLink(item: PropSidebarItemCategory): string | undefined;
+/**
+ * Gets the category associated with the current location. Should only be used
+ * on category index pages.
+ */
+export declare function useCurrentSidebarCategory(): PropSidebarItemCategory;
+/**
+ * Checks if a sidebar item should be active, based on the active path.
+ */
+export declare function isActiveSidebarItem(item: PropSidebarItem, activePath: string): boolean;
+/**
+ * Gets the breadcrumbs of the current doc page, based on its sidebar location.
+ * Returns `null` if there's no sidebar or breadcrumbs are disabled.
+ */
+export declare function useSidebarBreadcrumbs(): PropSidebarBreadcrumbsItem[] | null;
+/**
+ * "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 declare function useDocsVersionCandidates(docsPluginId?: string): [GlobalVersion, ...GlobalVersion[]];
+/**
+ * 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 declare function useLayoutDocsSidebar(sidebarId: string, docsPluginId?: string): GlobalSidebar;
+/**
+ * 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 declare function useLayoutDoc(docId: string, docsPluginId?: string): GlobalDoc | null;
+/**
+ * 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 declare 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;
+};
+//# sourceMappingURL=docsUtils.d.ts.map

package/lib/utils/docsUtils.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"docsUtils.d.ts","sourceRoot":"","sources":["../../src/utils/docsUtils.tsx"],"names":[],"mappings":"AAAA;;;;;GAKG;;AAGH,OAAO,EAKL,KAAK,aAAa,EAClB,KAAK,aAAa,EAClB,KAAK,SAAS,EACf,MAAM,wCAAwC,CAAC;AAChD,OAAO,KAAK,EACV,WAAW,EACX,eAAe,EACf,uBAAuB,EACvB,cAAc,EACd,0BAA0B,EAC3B,MAAM,iCAAiC,CAAC;AACzC,OAAO,KAAK,EAAC,KAAK,IAAI,YAAY,EAAC,MAAM,gBAAgB,CAAC;AAU1D,eAAO,MAAM,mBAAmB,EAAE,OAA0B,CAAC;AAE7D;;GAEG;AACH,wBAAgB,UAAU,CAAC,EAAE,EAAE,MAAM,GAAG,cAAc,CAAC;AACvD;;GAEG;AACH,wBAAgB,UAAU,CAAC,EAAE,EAAE,MAAM,GAAG,SAAS,GAAG,cAAc,GAAG,SAAS,CAAC;AAa/E;;GAEG;AACH,wBAAgB,mBAAmB,CACjC,OAAO,EAAE,WAAW,EACpB,SAAS,EAAE,CAAC,QAAQ,EAAE,uBAAuB,KAAK,OAAO,GACxD,uBAAuB,GAAG,SAAS,CAarC;AAED;;;GAGG;AACH,wBAAgB,qBAAqB,CACnC,IAAI,EAAE,uBAAuB,GAC5B,MAAM,GAAG,SAAS,CAiBpB;AAED;;;GAGG;AACH,wBAAgB,yBAAyB,IAAI,uBAAuB,CAenE;AASD;;GAEG;AACH,wBAAgB,mBAAmB,CACjC,IAAI,EAAE,eAAe,EACrB,UAAU,EAAE,MAAM,GACjB,OAAO,CAaT;AAED;;;GAGG;AACH,wBAAgB,qBAAqB,IAAI,0BAA0B,EAAE,GAAG,IAAI,CA6B3E;AAED;;;;;;;;;;;;;;;GAeG;AACH,wBAAgB,wBAAwB,CACtC,YAAY,CAAC,EAAE,MAAM,GACpB,CAAC,aAAa,EAAE,GAAG,aAAa,EAAE,CAAC,CAWrC;AAED;;;;;;;GAOG;AACH,wBAAgB,oBAAoB,CAClC,SAAS,EAAE,MAAM,EACjB,YAAY,CAAC,EAAE,MAAM,GACpB,aAAa,CAoBf;AAED;;;;;;;GAOG;AACH,wBAAgB,YAAY,CAC1B,KAAK,EAAE,MAAM,EACb,YAAY,CAAC,EAAE,MAAM,GACpB,SAAS,GAAG,IAAI,CAuBlB;AAGD;;;;;;;;GAQG;AACH,wBAAgB,mBAAmB,CAAC,EAClC,KAAK,EACL,eAAe,GAChB,EAAE,YAAY,GAAG,IAAI,GAAG;IACvB,mEAAmE;IACnE,UAAU,EAAE,GAAG,CAAC,OAAO,CAAC;IACxB;;;OAGG;IACH,WAAW,EAAE,MAAM,GAAG,SAAS,CAAC;IAChC,gEAAgE;IAChE,YAAY,EAAE,WAAW,GAAG,SAAS,CAAC;CACvC,CAwBA"}