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

package/lib/utils/codeBlockUtils.js

@@ -6,129 +6,160 @@
  */
 import rangeParser from 'parse-numeric-range';
 const codeBlockTitleRegex = /title=(?<quote>["'])(?<title>.*?)\1/;
-const highlightLinesRangeRegex = /{(?<range>[\d,-]+)}/;
-const commentTypes = ['js', 'jsBlock', 'jsx', 'python', 'html'];
+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: '',
-    },
-    html: {
-        start: '<!--',
-        end: '-->',
-    },
+    js: { start: '\\/\\/', end: '' },
+    jsBlock: { start: '\\/\\*', end: '\\*\\/' },
+    jsx: { start: '\\{\\s*\\/\\*', end: '\\*\\/\\s*\\}' },
+    bash: { start: '#', end: '' },
+    html: { start: '<!--', end: '-->' },
 };
-const magicCommentDirectives = [
-    'highlight-next-line',
-    'highlight-start',
-    'highlight-end',
-];
-const getMagicCommentDirectiveRegex = (languages = commentTypes) => {
-    // to be more reliable, the opening and closing comment must match
+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.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
-const magicCommentDirectiveRegex = (lang) => {
+}
+/**
+ * Select comment styles based on language
+ */
+function getAllMagicCommentDirectiveStyles(lang, magicCommentDirectives) {
     switch (lang) {
         case 'js':
         case 'javascript':
         case 'ts':
         case 'typescript':
-            return getMagicCommentDirectiveRegex(['js', 'jsBlock']);
+            return getCommentPattern(['js', 'jsBlock'], magicCommentDirectives);
         case 'jsx':
         case 'tsx':
-            return getMagicCommentDirectiveRegex(['js', 'jsBlock', 'jsx']);
+            return getCommentPattern(['js', 'jsBlock', 'jsx'], magicCommentDirectives);
         case 'html':
-            return getMagicCommentDirectiveRegex(['js', 'jsBlock', 'html']);
+            return getCommentPattern(['js', 'jsBlock', 'html'], magicCommentDirectives);
         case 'python':
         case 'py':
-            return getMagicCommentDirectiveRegex(['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 getMagicCommentDirectiveRegex();
+            // 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.groups.title) !== 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 === null || languageClassName === void 0 ? void 0 : languageClassName.replace(/language-/, '');
+    return languageClassName?.replace(/language-/, '');
 }
 /**
- * @param metastring The highlight range declared here starts at 1
- * @returns Note: all line numbers start at 0, not 1
+ * 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, metastring, language) {
+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 && 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 = magicCommentDirectiveRegex(language);
-    // go through line by line
+    const directiveRegex = getAllMagicCommentDirectiveStyles(language, magicComments);
+    // Go through line by line
     const lines = code.split('\n');
-    let highlightBlockStart;
-    let highlightRange = '';
-    // loop through lines
+    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 !== 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 = {};
+    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

@@ -1 +1 @@
-{"version":3,"file":"codeBlockUtils.js","sourceRoot":"","sources":["../../src/utils/codeBlockUtils.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"codeBlockUtils.js","sourceRoot":"","sources":["../../src/utils/codeBlockUtils.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAEH,OAAO,WAAW,MAAM,qBAAqB,CAAC;AAI9C,MAAM,mBAAmB,GAAG,qCAAqC,CAAC;AAClE,MAAM,yBAAyB,GAAG,uBAAuB,CAAC;AAE1D,wCAAwC;AACxC,MAAM,eAAe,GAAG;IACtB,EAAE,EAAE,EAAC,KAAK,EAAE,QAAQ,EAAE,GAAG,EAAE,EAAE,EAAC;IAC9B,OAAO,EAAE,EAAC,KAAK,EAAE,QAAQ,EAAE,GAAG,EAAE,QAAQ,EAAC;IACzC,GAAG,EAAE,EAAC,KAAK,EAAE,eAAe,EAAE,GAAG,EAAE,eAAe,EAAC;IACnD,IAAI,EAAE,EAAC,KAAK,EAAE,GAAG,EAAE,GAAG,EAAE,EAAE,EAAC;IAC3B,IAAI,EAAE,EAAC,KAAK,EAAE,MAAM,EAAE,GAAG,EAAE,KAAK,EAAC;CAClC,CAAC;AAUF,SAAS,iBAAiB,CACxB,SAAwB,EACxB,sBAA4C;IAE5C,kEAAkE;IAClE,MAAM,cAAc,GAAG,SAAS;SAC7B,GAAG,CAAC,CAAC,IAAI,EAAE,EAAE;QACZ,MAAM,EAAC,KAAK,EAAE,GAAG,EAAC,GAAG,eAAe,CAAC,IAAI,CAAC,CAAC;QAC3C,OAAO,MAAM,KAAK,QAAQ,sBAAsB;aAC7C,OAAO,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,CAAC,IAAI,EAAE,CAAC,CAAC,KAAK,EAAE,KAAK,EAAE,CAAC,CAAC,KAAK,EAAE,GAAG,CAAC,CAAC,MAAM,CAAC,OAAO,CAAC,CAAC;aACtE,IAAI,CAAC,GAAG,CAAC,QAAQ,GAAG,GAAG,CAAC;IAC7B,CAAC,CAAC;SACD,IAAI,CAAC,GAAG,CAAC,CAAC;IACb,sEAAsE;IACtE,OAAO,IAAI,MAAM,CAAC,WAAW,cAAc,QAAQ,CAAC,CAAC;AACvD,CAAC;AAED;;GAEG;AACH,SAAS,iCAAiC,CACxC,IAAY,EACZ,sBAA4C;IAE5C,QAAQ,IAAI,EAAE;QACZ,KAAK,IAAI,CAAC;QACV,KAAK,YAAY,CAAC;QAClB,KAAK,IAAI,CAAC;QACV,KAAK,YAAY;YACf,OAAO,iBAAiB,CAAC,CAAC,IAAI,EAAE,SAAS,CAAC,EAAE,sBAAsB,CAAC,CAAC;QAEtE,KAAK,KAAK,CAAC;QACX,KAAK,KAAK;YACR,OAAO,iBAAiB,CACtB,CAAC,IAAI,EAAE,SAAS,EAAE,KAAK,CAAC,EACxB,sBAAsB,CACvB,CAAC;QAEJ,KAAK,MAAM;YACT,OAAO,iBAAiB,CACtB,CAAC,IAAI,EAAE,SAAS,EAAE,MAAM,CAAC,EACzB,sBAAsB,CACvB,CAAC;QAEJ,KAAK,QAAQ,CAAC;QACd,KAAK,IAAI,CAAC;QACV,KAAK,MAAM;YACT,OAAO,iBAAiB,CAAC,CAAC,MAAM,CAAC,EAAE,sBAAsB,CAAC,CAAC;QAE7D,KAAK,UAAU,CAAC;QAChB,KAAK,IAAI;YACP,yCAAyC;YACzC,OAAO,iBAAiB,CAAC,CAAC,MAAM,EAAE,KAAK,EAAE,MAAM,CAAC,EAAE,sBAAsB,CAAC,CAAC;QAE5E;YACE,oBAAoB;YACpB,OAAO,iBAAiB,CACtB,MAAM,CAAC,IAAI,CAAC,eAAe,CAAkB,EAC7C,sBAAsB,CACvB,CAAC;KACL;AACH,CAAC;AAED,MAAM,UAAU,mBAAmB,CAAC,UAAmB;IACrD,OAAO,UAAU,EAAE,KAAK,CAAC,mBAAmB,CAAC,EAAE,MAAO,CAAC,KAAK,IAAI,EAAE,CAAC;AACrE,CAAC;AAED,MAAM,UAAU,mBAAmB,CAAC,UAAmB;IACrD,OAAO,UAAU,EAAE,QAAQ,CAAC,iBAAiB,CAAC,IAAI,KAAK,CAAC;AAC1D,CAAC;AAED;;;;GAIG;AACH,MAAM,UAAU,aAAa,CAAC,SAAiB;IAC7C,MAAM,iBAAiB,GAAG,SAAS;SAChC,KAAK,CAAC,GAAG,CAAC;SACV,IAAI,CAAC,CAAC,GAAG,EAAE,EAAE,CAAC,GAAG,CAAC,UAAU,CAAC,WAAW,CAAC,CAAC,CAAC;IAC9C,OAAO,iBAAiB,EAAE,OAAO,CAAC,WAAW,EAAE,EAAE,CAAC,CAAC;AACrD,CAAC;AAED;;;;;;;;;;;;GAYG;AACH,MAAM,UAAU,UAAU,CACxB,OAAe,EACf,OAgBC;IAcD,IAAI,IAAI,GAAG,OAAO,CAAC,OAAO,CAAC,KAAK,EAAE,EAAE,CAAC,CAAC;IACtC,MAAM,EAAC,QAAQ,EAAE,aAAa,EAAE,UAAU,EAAC,GAAG,OAAO,CAAC;IACtD,gEAAgE;IAChE,IAAI,UAAU,IAAI,yBAAyB,CAAC,IAAI,CAAC,UAAU,CAAC,EAAE;QAC5D,MAAM,UAAU,GAAG,UAAU,CAAC,KAAK,CAAC,yBAAyB,CAAE,CAAC,MAAO;aACpE,KAAM,CAAC;QACV,IAAI,aAAa,CAAC,MAAM,KAAK,CAAC,EAAE;YAC9B,MAAM,IAAI,KAAK,CACb,uEAAuE,UAAU,kIAAkI,CACpN,CAAC;SACH;QACD,MAAM,wBAAwB,GAAG,aAAa,CAAC,CAAC,CAAE,CAAC,SAAS,CAAC;QAC7D,MAAM,KAAK,GAAG,WAAW,CAAC,UAAU,CAAC;aAClC,MAAM,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,GAAG,CAAC,CAAC;aACpB,GAAG,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,GAAG,CAAC,EAAE,CAAC,wBAAwB,CAAC,CAAC,CAAC,CAAC;QACnD,OAAO,EAAC,cAAc,EAAE,MAAM,CAAC,WAAW,CAAC,KAAK,CAAC,EAAE,IAAI,EAAC,CAAC;KAC1D;IACD,IAAI,QAAQ,KAAK,SAAS,EAAE;QAC1B,OAAO,EAAC,cAAc,EAAE,EAAE,EAAE,IAAI,EAAC,CAAC;KACnC;IACD,MAAM,cAAc,GAAG,iCAAiC,CACtD,QAAQ,EACR,aAAa,CACd,CAAC;IACF,0BAA0B;IAC1B,MAAM,KAAK,GAAG,IAAI,CAAC,KAAK,CAAC,IAAI,CAAC,CAAC;IAC/B,MAAM,MAAM,GAAG,MAAM,CAAC,WAAW,CAC/B,aAAa,CAAC,GAAG,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,CAAC,SAAS,EAAE,EAAC,KAAK,EAAE,CAAC,EAAE,KAAK,EAAE,EAAE,EAAC,CAAC,CAAC,CAC/D,CAAC;IACF,MAAM,eAAe,GAAgC,MAAM,CAAC,WAAW,CACrE,aAAa;SACV,MAAM,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,IAAI,CAAC;SACrB,GAAG,CAAC,CAAC,EAAC,SAAS,EAAE,IAAI,EAAC,EAAE,EAAE,CAAC,CAAC,IAAI,EAAE,SAAS,CAAC,CAAC,CACjD,CAAC;IACF,MAAM,qBAAqB,GAAgC,MAAM,CAAC,WAAW,CAC3E,aAAa;SACV,MAAM,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,KAAK,CAAC;SACtB,GAAG,CAAC,CAAC,EAAC,SAAS,EAAE,KAAK,EAAC,EAAE,EAAE,CAAC,CAAC,KAAM,CAAC,KAAK,EAAE,SAAS,CAAC,CAAC,CAC1D,CAAC;IACF,MAAM,mBAAmB,GAAgC,MAAM,CAAC,WAAW,CACzE,aAAa;SACV,MAAM,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,KAAK,CAAC;SACtB,GAAG,CAAC,CAAC,EAAC,SAAS,EAAE,KAAK,EAAC,EAAE,EAAE,CAAC,CAAC,KAAM,CAAC,GAAG,EAAE,SAAS,CAAC,CAAC,CACxD,CAAC;IACF,KAAK,IAAI,UAAU,GAAG,CAAC,EAAE,UAAU,GAAG,KAAK,CAAC,MAAM,GAAI;QACpD,MAAM,IAAI,GAAG,KAAK,CAAC,UAAU,CAAE,CAAC;QAChC,MAAM,KAAK,GAAG,IAAI,CAAC,KAAK,CAAC,cAAc,CAAC,CAAC;QACzC,IAAI,CAAC,KAAK,EAAE;YACV,yCAAyC;YACzC,UAAU,IAAI,CAAC,CAAC;YAChB,SAAS;SACV;QACD,MAAM,SAAS,GAAG,KAAK,CAAC,KAAK,CAAC,CAAC,CAAC,CAAC,IAAI,CAAC,CAAC,IAAI,EAAE,EAAE,CAAC,IAAI,KAAK,SAAS,CAAE,CAAC;QACrE,IAAI,eAAe,CAAC,SAAS,CAAC,EAAE;YAC9B,MAAM,CAAC,eAAe,CAAC,SAAS,CAAE,CAAE,CAAC,KAAK,IAAI,GAAG,UAAU,GAAG,CAAC;SAChE;aAAM,IAAI,qBAAqB,CAAC,SAAS,CAAC,EAAE;YAC3C,MAAM,CAAC,qBAAqB,CAAC,SAAS,CAAE,CAAE,CAAC,KAAK,GAAG,UAAU,CAAC;SAC/D;aAAM,IAAI,mBAAmB,CAAC,SAAS,CAAC,EAAE;YACzC,MAAM,CAAC,mBAAmB,CAAC,SAAS,CAAE,CAAE,CAAC,KAAK,IAAI,GAChD,MAAM,CAAC,mBAAmB,CAAC,SAAS,CAAE,CAAE,CAAC,KAC3C,IAAI,UAAU,GAAG,CAAC,GAAG,CAAC;SACvB;QACD,KAAK,CAAC,MAAM,CAAC,UAAU,EAAE,CAAC,CAAC,CAAC;KAC7B;IACD,IAAI,GAAG,KAAK,CAAC,IAAI,CAAC,IAAI,CAAC,CAAC;IACxB,MAAM,cAAc,GAAoC,EAAE,CAAC;IAC3D,MAAM,CAAC,OAAO,CAAC,MAAM,CAAC,CAAC,OAAO,CAAC,CAAC,CAAC,SAAS,EAAE,EAAC,KAAK,EAAC,CAAC,EAAE,EAAE;QACtD,WAAW,CAAC,KAAK,CAAC,CAAC,OAAO,CAAC,CAAC,CAAC,EAAE,EAAE;YAC/B,cAAc,CAAC,CAAC,MAAhB,cAAc,CAAC,CAAC,IAAM,EAAE,EAAC;YACzB,cAAc,CAAC,CAAC,CAAE,CAAC,IAAI,CAAC,SAAS,CAAC,CAAC;QACrC,CAAC,CAAC,CAAC;IACL,CAAC,CAAC,CAAC;IACH,OAAO,EAAC,cAAc,EAAE,IAAI,EAAC,CAAC;AAChC,CAAC;AAED,MAAM,UAAU,oBAAoB,CAAC,UAAsB;IACzD,MAAM,OAAO,GAAgD;QAC3D,KAAK,EAAE,eAAe;QACtB,eAAe,EAAE,0BAA0B;KAC5C,CAAC;IAEF,MAAM,UAAU,GAA4B,EAAE,CAAC;IAC/C,MAAM,CAAC,OAAO,CAAC,UAAU,CAAC,KAAK,CAAC,CAAC,OAAO,CAAC,CAAC,CAAC,GAAG,EAAE,KAAK,CAAC,EAAE,EAAE;QACxD,MAAM,OAAO,GAAG,OAAO,CAAC,GAAG,CAAC,CAAC;QAC7B,IAAI,OAAO,IAAI,OAAO,KAAK,KAAK,QAAQ,EAAE;YACxC,UAAU,CAAC,OAAO,CAAC,GAAG,KAAK,CAAC;SAC7B;IACH,CAAC,CAAC,CAAC;IACH,OAAO,UAAU,CAAC;AACpB,CAAC"}

package/lib/utils/docsUtils.d.ts

@@ -4,30 +4,95 @@
  * This source code is licensed under the MIT license found in the
  * LICENSE file in the root directory of this source tree.
  */
-import { type ReactNode } from 'react';
-import type { PropSidebar, PropSidebarItem, PropSidebarItemCategory, PropVersionDoc, PropVersionMetadata, PropSidebarBreadcrumbsItem } from '@docusaurus/plugin-content-docs';
+/// <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;
-declare const EmptyContextValue: unique symbol;
-export declare function DocsVersionProvider({ children, version, }: {
-    children: ReactNode;
-    version: PropVersionMetadata | typeof EmptyContextValue;
-}): JSX.Element;
-export declare function useDocsVersion(): PropVersionMetadata;
+/**
+ * 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;
-export declare function DocsSidebarProvider({ children, sidebar, }: {
-    children: ReactNode;
-    sidebar: PropSidebar | null;
-}): JSX.Element;
-export declare function useDocsSidebar(): PropSidebar | null;
+/**
+ * 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;
-export declare function getBreadcrumbs({ sidebar, pathname, }: {
-    sidebar: PropSidebar;
-    pathname: string;
-}): PropSidebarBreadcrumbsItem[];
+/**
+ * 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;
-export {};
+/**
+ * "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

@@ -1 +1 @@
-{"version":3,"file":"docsUtils.d.ts","sourceRoot":"","sources":["../../src/utils/docsUtils.tsx"],"names":[],"mappings":"AAAA;;;;;GAKG;AAEH,OAAc,EAAgB,KAAK,SAAS,EAAa,MAAM,OAAO,CAAC;AAKvE,OAAO,KAAK,EACV,WAAW,EACX,eAAe,EACf,uBAAuB,EACvB,cAAc,EACd,mBAAmB,EACnB,0BAA0B,EAC3B,MAAM,iCAAiC,CAAC;AAKzC,eAAO,MAAM,mBAAmB,EAAE,OAA0B,CAAC;AAI7D,QAAA,MAAM,iBAAiB,EAAE,OAAO,MAA+B,CAAC;AAMhE,wBAAgB,mBAAmB,CAAC,EAClC,QAAQ,EACR,OAAO,GACR,EAAE;IACD,QAAQ,EAAE,SAAS,CAAC;IACpB,OAAO,EAAE,mBAAmB,GAAG,OAAO,iBAAiB,CAAC;CACzD,GAAG,GAAG,CAAC,OAAO,CAMd;AAED,wBAAgB,cAAc,IAAI,mBAAmB,CAMpD;AAED,wBAAgB,UAAU,CAAC,EAAE,EAAE,MAAM,GAAG,cAAc,CAAC;AACvD,wBAAgB,UAAU,CAAC,EAAE,EAAE,MAAM,GAAG,SAAS,GAAG,cAAc,GAAG,SAAS,CAAC;AAiB/E,wBAAgB,mBAAmB,CAAC,EAClC,QAAQ,EACR,OAAO,GACR,EAAE;IACD,QAAQ,EAAE,SAAS,CAAC;IACpB,OAAO,EAAE,WAAW,GAAG,IAAI,CAAC;CAC7B,GAAG,GAAG,CAAC,OAAO,CAMd;AAED,wBAAgB,cAAc,IAAI,WAAW,GAAG,IAAI,CAMnD;AAID,wBAAgB,mBAAmB,CACjC,OAAO,EAAE,WAAW,EACpB,SAAS,EAAE,CAAC,QAAQ,EAAE,uBAAuB,KAAK,OAAO,GACxD,uBAAuB,GAAG,SAAS,CAarC;AAGD,wBAAgB,qBAAqB,CACnC,IAAI,EAAE,uBAAuB,GAC5B,MAAM,GAAG,SAAS,CAsBpB;AAED,wBAAgB,yBAAyB,IAAI,uBAAuB,CAgBnE;AASD,wBAAgB,mBAAmB,CACjC,IAAI,EAAE,eAAe,EACrB,UAAU,EAAE,MAAM,GACjB,OAAO,CAeT;AAED,wBAAgB,cAAc,CAAC,EAC7B,OAAO,EACP,QAAQ,GACT,EAAE;IACD,OAAO,EAAE,WAAW,CAAC;IACrB,QAAQ,EAAE,MAAM,CAAC;CAClB,GAAG,0BAA0B,EAAE,CAuB/B;AAED,wBAAgB,qBAAqB,IAAI,0BAA0B,EAAE,GAAG,IAAI,CAU3E"}
+{"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"}