@ng-doc/utils 22.0.0 → 22.2.0

package/index.esm.js

@@ -7,6 +7,9 @@ import { isElement as isElement$1 } from 'hast-util-is-element';
 import { toString } from 'hast-util-to-string';
 import { visitParents, SKIP } from 'unist-util-visit-parents';
 import rehypeShiki from '@shikijs/rehype';
+import rehypeShikiFromHighlighter from '@shikijs/rehype/core';
+import { createHash } from 'node:crypto';
+import { createHighlighter, bundledLanguages } from 'shiki';
 import { visit } from 'unist-util-visit';
 import GithubSlugger from 'github-slugger';
 import { hasProperty } from 'hast-util-has-property';
@@ -90,8 +93,472 @@ function isHeading(node) {
     return isElement$1(node, HEADINGS);
 }
 
+/**
+ * Where a keyword may link inside code.
+ *
+ * The keywords plugin splits code into words and looks each one up. A word that happens to be a
+ * keyword is not always a reference to it: an object key (`group: 'Colors'`), a property after a
+ * dot, a string, an HTML attribute value or a file name in inline code (`vite.config.mjs`) only
+ * share its name. Highlighted code carries no token scopes (Shiki emits colours only, and adjacent
+ * tokens of one colour are merged), so this module reads the position of a word from the code text
+ * itself with a small lexer: strings and comments, the characters around the word, and the names
+ * the code declares. The result only depends on the code, never on the keyword set, so the words a
+ * page records as used keywords are exactly the ones that may link.
+ */
+const WORD_CHARACTER = /[*\p{L}\w$@-]/u;
+const IDENTIFIER_BEFORE = /[\p{L}\w$@-]+$/u;
+const WHOLE_KEYWORD = /^\s*[*\p{L}\w$@-]+(?:[.#][\p{L}\w-]+)?(?:\?[\w=&]+)?\s*$/u;
+/** Characters that make inline code read as TypeScript rather than as a name, path or prose. */
+const CODE_PUNCTUATION = /[(){}[\]<>|:=@]/;
+/** Inline code that starts like a TypeScript declaration. */
+const DECLARATION_START = /^\s*(?:export|import|class|interface|type|const|let|var|function|enum|abstract|declare)\s/;
+/** Inline code that starts with an HTML tag. */
+const HTML_START = /^\s*<\/?[A-Za-z]/;
+/** Syntax words. They never link, even before `(` (`if (`, `function (`, `super(`). */
+const SYNTAX_WORDS = new Set([
+    'await',
+    'break',
+    'case',
+    'catch',
+    'continue',
+    'debugger',
+    'delete',
+    'do',
+    'else',
+    'false',
+    'finally',
+    'for',
+    'function',
+    'if',
+    'instanceof',
+    'new',
+    'null',
+    'return',
+    'super',
+    'switch',
+    'this',
+    'throw',
+    'true',
+    'try',
+    'typeof',
+    'void',
+    'while',
+    'with',
+    'yield',
+]);
+/**
+ * TypeScript keywords and modifiers that are also valid names. They link only when called, so that
+ * RxJS `of(…)` and `from(…)` still link while `readonly` in `readonly size = input()` or `from`
+ * in an import does not.
+ */
+const RESERVED_WORDS = new Set([
+    'abstract',
+    'accessor',
+    'any',
+    'as',
+    'asserts',
+    'async',
+    'bigint',
+    'boolean',
+    'class',
+    'const',
+    'constructor',
+    'declare',
+    'default',
+    'enum',
+    'export',
+    'extends',
+    'from',
+    'get',
+    'implements',
+    'import',
+    'in',
+    'infer',
+    'interface',
+    'is',
+    'keyof',
+    'let',
+    'module',
+    'namespace',
+    'never',
+    'number',
+    'object',
+    'of',
+    'out',
+    'override',
+    'package',
+    'private',
+    'protected',
+    'public',
+    'readonly',
+    'require',
+    'satisfies',
+    'set',
+    'static',
+    'string',
+    'symbol',
+    'type',
+    'undefined',
+    'unique',
+    'unknown',
+    'var',
+]);
+/** The characters before a name in a type position: `: Type`, `A | B`, `A & B`, `Generic<Type`. */
+const TYPE_CONTEXT = [':', '|', '&', '<'];
+/** The words before a name in a type position, or before a type alias's name. */
+const TYPE_WORDS = ['type', 'extends', 'keyof', 'typeof'];
+/** What a character of code is, in a scan's marks. */
+const CODE = 0;
+const STRING = 1;
+const COMMENT = 2;
+/** The text of a TypeScript template literal, outside its `${…}` expressions. */
+const TEMPLATE = 3;
+/** An Angular control flow block in an inline template (`@if`, `@for`, `@defer`). */
+const CONTROL_FLOW = /^@[a-z]+$/;
+const NOT_A_REFERENCE = Object.freeze({ link: false });
+const REFERENCE = Object.freeze({ link: true });
+/**
+ * The positions of the words of inline code, or `undefined` when no word of it may link.
+ *
+ * Inline code links when it is one keyword reference as a whole (`NgDocPage`, `*GuidePage#anchor`,
+ * `NgDocPage.title`, with an optional `?query`), or when it reads as TypeScript: it contains code
+ * punctuation (a call, generics, a union, an array type, a decorator, a type annotation) or starts
+ * with a declaration. Then its words link where they would in a TypeScript code block. Anything
+ * else (a file name like `vite.ng-doc.config.mjs`, a path, a command, prose, an HTML tag) stays
+ * plain text.
+ * @param text - The text of the inline code element.
+ */
+function scanInlineCode(text) {
+    if (WHOLE_KEYWORD.test(text)) {
+        return { whole: true, position: () => REFERENCE };
+    }
+    if (HTML_START.test(text) || !(CODE_PUNCTUATION.test(text) || DECLARATION_START.test(text))) {
+        return undefined;
+    }
+    const scan = scanTypeScript(text);
+    // A message or a sentence with some punctuation (`Refusing to overwrite unowned output`) is not
+    // code: TypeScript never has three plain names in a row.
+    return isProse(text, scan.masked) ? undefined : scan;
+}
+/**
+ * The positions of the words of a code block.
+ * @param text - The text of the block's `code` element.
+ * @param mode - How the block's language is read.
+ */
+function scanCodeBlock(text, mode) {
+    return mode === 'html' ? scanHtml(text) : scanTypeScript(text);
+}
+/**
+ * TypeScript: a word links unless it is inside a string or a comment (in a template literal, only
+ * Angular control flow blocks and the names of custom elements link), a syntax word, a reserved
+ * word that is not called, a property after a dot (it then links only as a whole `Owner.member`
+ * keyword), a declared name (an object key, a property, a parameter or a variable before `:`,
+ * `?:`, `!:` or `=`), or a name the code binds itself (`const`/`let`/`var`, or an import from a
+ * relative module).
+ * @param text - The code.
+ */
+function scanTypeScript(text) {
+    const masked = maskTypeScript(text);
+    const locals = localBindings(text, masked);
+    return {
+        whole: false,
+        masked,
+        position(start, end, key) {
+            if (masked[start] === TEMPLATE) {
+                // A template literal is usually an inline Angular template: its control flow blocks and
+                // the names of custom elements (`<ng-content>`, `</ng-container>`; a standard element
+                // such as `<input>` has no dash) refer to Angular and components, while its attributes
+                // and text are the template's own.
+                const before = text[start - 1] ?? '';
+                const element = key.includes('-') && (before === '<' || (before === '/' && text[start - 2] === '<'));
+                const controlFlow = CONTROL_FLOW.test(key) && !WORD_CHARACTER.test(before);
+                return element || controlFlow ? REFERENCE : NOT_A_REFERENCE;
+            }
+            if (masked[start] !== CODE) {
+                return NOT_A_REFERENCE;
+            }
+            const previous = previousSignificant(text, start, masked);
+            const next = nextSignificant(text, end, masked);
+            const nextCharacter = text[next] ?? '';
+            if (SYNTAX_WORDS.has(key) || (RESERVED_WORDS.has(key) && nextCharacter !== '(')) {
+                return NOT_A_REFERENCE;
+            }
+            if (text[previous] === '.' && text[previous - 1] !== '.') {
+                // `owner.member` and `owner?.member`
+                const ownerEnd = text[previous - 1] === '?' ? previous - 1 : previous;
+                const owner = text.slice(0, ownerEnd).match(IDENTIFIER_BEFORE)?.[0];
+                const word = text.slice(start, end);
+                return owner && !/[.#]/.test(word)
+                    ? { link: true, keyword: `${owner}.${key.toLowerCase()}` }
+                    : NOT_A_REFERENCE;
+            }
+            if (isDeclaredName(text, masked, previous, next)) {
+                return NOT_A_REFERENCE;
+            }
+            return locals.has(key) ? NOT_A_REFERENCE : REFERENCE;
+        },
+    };
+}
+/**
+ * Whether the word between `previous` and `next` is a name being declared rather than used.
+ * @param text - The code.
+ * @param masked - The marks of its strings and comments.
+ * @param previous - The index of the significant character before the word, or -1.
+ * @param next - The index of the significant character after the word.
+ */
+function isDeclaredName(text, masked, previous, next) {
+    const after = text[next];
+    const afterNext = text[nextSignificant(text, next + 1, masked)];
+    if (after === ':' && text[next + 1] !== ':') {
+        // `cond ? Value : other` and `case Value:` use the name.
+        const ternary = text[previous] === '?' && text[previous + 1] !== '.';
+        return !ternary && previousWord(text, previous) !== 'case';
+    }
+    if ((after === '?' || after === '!') && afterNext === ':') {
+        return true;
+    }
+    if (after === '?' && (afterNext === ')' || afterNext === ',')) {
+        return true;
+    }
+    if (after === '=' && text[next + 1] !== '=' && text[next + 1] !== '>') {
+        // A type before `=` (`size: NgDocSize = …`, `<T extends Base = Base>`) is used, and
+        // `type Name = …` declares a type alias, which is linked like a class.
+        return (!TYPE_CONTEXT.includes(text[previous] ?? '') &&
+            !TYPE_WORDS.includes(previousWord(text, previous)));
+    }
+    return false;
+}
+/**
+ * HTML: a word links unless it is inside a comment or an attribute value. Which keywords may link
+ * in HTML at all (the selectors of components and directives) is decided by their languages.
+ * @param text - The code.
+ */
+function scanHtml(text) {
+    const masked = maskHtml(text);
+    return {
+        whole: false,
+        position: (start) => (masked[start] === CODE ? REFERENCE : NOT_A_REFERENCE),
+    };
+}
+/**
+ * Marks the characters of TypeScript strings and comments. The `${…}` expressions of template
+ * literals stay code. Regular expression literals are not recognised.
+ * @param text - The code.
+ */
+function maskTypeScript(text) {
+    const masked = new Uint8Array(text.length);
+    // The brace depth of every open `${` of a template literal, innermost last.
+    const templates = [];
+    let depth = 0;
+    let index = 0;
+    const string = (quote) => {
+        const start = index++;
+        while (index < text.length && text[index] !== quote && text[index] !== '\n') {
+            index += text[index] === '\\' ? 2 : 1;
+        }
+        masked.fill(STRING, start, Math.min(++index, text.length));
+    };
+    const template = () => {
+        const start = index++;
+        while (index < text.length && text[index] !== '`') {
+            if (text[index] === '\\') {
+                index += 2;
+            }
+            else if (text[index] === '$' && text[index + 1] === '{') {
+                masked.fill(TEMPLATE, start, index);
+                templates.push(depth);
+                index += 2;
+                return;
+            }
+            else {
+                index++;
+            }
+        }
+        masked.fill(TEMPLATE, start, Math.min(++index, text.length));
+    };
+    while (index < text.length) {
+        const character = text[index];
+        if (character === '/' && text[index + 1] === '/') {
+            const end = text.indexOf('\n', index);
+            const stop = end < 0 ? text.length : end;
+            masked.fill(COMMENT, index, stop);
+            index = stop;
+        }
+        else if (character === '/' && text[index + 1] === '*') {
+            const end = text.indexOf('*/', index + 2);
+            const stop = end < 0 ? text.length : end + 2;
+            masked.fill(COMMENT, index, stop);
+            index = stop;
+        }
+        else if (character === "'" || character === '"') {
+            string(character);
+        }
+        else if (character === '`') {
+            template();
+        }
+        else if (character === '{') {
+            depth++;
+            index++;
+        }
+        else if (character === '}') {
+            if (templates.length && templates[templates.length - 1] === depth) {
+                // The end of a `${…}` expression: the template literal goes on.
+                templates.pop();
+                template();
+            }
+            else {
+                depth--;
+                index++;
+            }
+        }
+        else {
+            index++;
+        }
+    }
+    return masked;
+}
+/**
+ * Marks the characters of HTML comments and attribute values.
+ * @param text - The code.
+ */
+function maskHtml(text) {
+    const masked = new Uint8Array(text.length);
+    let index = 0;
+    while (index < text.length) {
+        if (text.startsWith('<!--', index)) {
+            const end = text.indexOf('-->', index + 4);
+            const stop = end < 0 ? text.length : end + 3;
+            masked.fill(COMMENT, index, stop);
+            index = stop;
+        }
+        else if (text[index] === '<' && /[A-Za-z/]/.test(text[index + 1] ?? '')) {
+            index = maskTag(text, index + 1, masked);
+        }
+        else {
+            index++;
+        }
+    }
+    return masked;
+}
+/**
+ * Marks the attribute values of the tag that starts at `index` and returns the index after it.
+ * @param text - The code.
+ * @param index - The index after the tag's `<`.
+ * @param masked - The marks.
+ */
+function maskTag(text, index, masked) {
+    while (index < text.length && text[index] !== '>') {
+        if (text[index] !== '=') {
+            index++;
+            continue;
+        }
+        index++;
+        while (text[index] === ' ' || text[index] === '\t' || text[index] === '\n')
+            index++;
+        const quote = text[index];
+        const start = index;
+        if (quote === '"' || quote === "'") {
+            const end = text.indexOf(quote, index + 1);
+            index = end < 0 ? text.length : end + 1;
+        }
+        else {
+            while (index < text.length && !/[\s>]/.test(text[index] ?? ''))
+                index++;
+        }
+        masked.fill(STRING, start, index);
+    }
+    return index + 1;
+}
+/**
+ * The names the code binds itself: `const`, `let` and `var` declarations and the names imported
+ * from relative modules. A use of such a name refers to the code's own binding, not to a keyword
+ * of the same name (`const config = …; export default config;`).
+ * @param text - The code.
+ * @param masked - The marks of its strings and comments.
+ */
+function localBindings(text, masked) {
+    const names = new Set();
+    for (const match of text.matchAll(/\b(?:const|let|var)\s+([\p{L}_$][\p{L}\w$]*)/gu)) {
+        if (!masked[match.index])
+            names.add(match[1] ?? '');
+    }
+    for (const match of text.matchAll(/\bimport\s+(?:type\s+)?([^;]*?)\s+from\s+(['"])\.{1,2}\/[^'"]*\2/gu)) {
+        if (masked[match.index])
+            continue;
+        for (const name of (match[1] ?? '').matchAll(/([\p{L}_$][\p{L}\w$]*)(?:\s+as\s+([\p{L}_$][\p{L}\w$]*))?/gu)) {
+            const local = name[2] ?? name[1] ?? '';
+            if (local !== 'type' && local !== 'as')
+                names.add(local);
+        }
+    }
+    return names;
+}
+/**
+ * Whether inline code reads as a sentence: three plain names in a row, separated by spaces only,
+ * outside strings and comments.
+ * @param text - The inline code.
+ * @param masked - The marks of its strings and comments.
+ */
+function isProse(text, masked) {
+    for (const match of text.matchAll(/[\p{L}_$][\p{L}\w$]*(?: [\p{L}_$][\p{L}\w$]*){2,}/gu)) {
+        const words = match[0].split(' ');
+        const plain = words.filter((word) => !SYNTAX_WORDS.has(word) && !RESERVED_WORDS.has(word));
+        if (!masked[match.index] && plain.length >= 3) {
+            return true;
+        }
+    }
+    return false;
+}
+/**
+ * The index of the last character before `index` that is neither whitespace nor in a comment, or
+ * -1.
+ * @param text - The code.
+ * @param index - The index to look back from.
+ * @param masked - The marks of its strings and comments.
+ */
+function previousSignificant(text, index, masked) {
+    let position = index - 1;
+    while (position >= 0 && insignificant(text, position, masked))
+        position--;
+    return position;
+}
+/**
+ * The index of the first character at or after `index` that is neither whitespace nor in a
+ * comment.
+ * @param text - The code.
+ * @param index - The index to look from.
+ * @param masked - The marks of its strings and comments.
+ */
+function nextSignificant(text, index, masked) {
+    let position = index;
+    while (position < text.length && insignificant(text, position, masked))
+        position++;
+    return position;
+}
+/**
+ * Whether the character at `index` is whitespace or part of a comment.
+ * @param text - The code.
+ * @param index - The index of the character.
+ * @param masked - The marks of its strings and comments.
+ */
+function insignificant(text, index, masked) {
+    return masked[index] === COMMENT || /\s/.test(text[index] ?? '');
+}
+/**
+ * The word that ends at `index` (inclusive), or an empty string.
+ * @param text - The code.
+ * @param index - The index of the word's last character.
+ */
+function previousWord(text, index) {
+    let start = index;
+    while (start >= 0 && WORD_CHARACTER.test(text[start] ?? ''))
+        start--;
+    return text.slice(start + 1, index + 1);
+}
+
 const ALWAYS_ALLOWED_LANGUAGES = ['typescript', 'ts', 'angular-ts'];
-const LANGUAGES = ['typescript', 'ts', 'angular-ts', ...KEYWORD_ALLOWED_LANGUAGES];
+const HTML_LANGUAGES = [...KEYWORD_ALLOWED_LANGUAGES];
+const LANGUAGES = [...ALWAYS_ALLOWED_LANGUAGES, ...HTML_LANGUAGES];
 const SPLIT_REGEXP = /([*\p{L}\w$@-]+(?:[.#][\p{L}\w-]+)?(?:\?[\w=&]+)?)/u;
 const MATCH_KEYWORD_REGEXP = /(?<key>[*\p{L}\w$@-]+)((?<delimiter>[.#])(?<anchor>[\p{L}\w-]+))?(?<queryParams>\?[\w=&]+)?/u;
 /**
@@ -107,25 +574,49 @@ function keywordsPlugin(config) {
         const lang = asArray(node.properties?.['className'] ?? [])
             .find((className) => className.startsWith('language-'))
             ?.replace('language-', '') ?? '';
-        if (isInlineCode || LANGUAGES.includes(lang)) {
-            visitParents(node, 'text', (node, ancestors) => {
-                if (hasLinkAncestor(ancestors)) {
-                    return;
-                }
-                const parent = ancestors[ancestors.length - 1];
-                const index = parent.children.indexOf(node);
-                // Parse the text for words that we can convert to links
-                const nodes = getNodes(node, parent, isInlineCode, config, lang);
-                // Replace the text node with the links and leftover text nodes
-                // eslint-disable-next-line @typescript-eslint/ban-ts-comment
-                // @ts-ignore
-                Array.prototype.splice.apply(parent.children, [index, 1].concat(nodes));
-                // Do not visit this node's children or the newly added nodes
-                return [SKIP, index + nodes.length];
-            });
+        if (!isInlineCode && !LANGUAGES.includes(lang)) {
+            return;
+        }
+        const offsets = textOffsets(node);
+        const text = Array.from(offsets.keys())
+            .map((textNode) => textNode.value)
+            .join('');
+        const scan = isInlineCode
+            ? scanInlineCode(text)
+            : scanCodeBlock(text, HTML_LANGUAGES.includes(lang) ? 'html' : 'typescript');
+        if (!scan) {
+            return;
         }
+        visitParents(node, 'text', (node, ancestors) => {
+            if (hasLinkAncestor(ancestors)) {
+                return;
+            }
+            const parent = ancestors[ancestors.length - 1];
+            const index = parent.children.indexOf(node);
+            // Parse the text for words that we can convert to links
+            const nodes = getNodes(node, parent, isInlineCode, config, lang, scan, offsets.get(node) ?? 0);
+            // Replace the text node with the links and leftover text nodes
+            // eslint-disable-next-line @typescript-eslint/ban-ts-comment
+            // @ts-ignore
+            Array.prototype.splice.apply(parent.children, [index, 1].concat(nodes));
+            // Do not visit this node's children or the newly added nodes
+            return [SKIP, index + nodes.length];
+        });
     });
 }
+/**
+ * The offset of every text node of a code element in the element's text, in document order.
+ * @param node - The code element.
+ */
+function textOffsets(node) {
+    const offsets = new Map();
+    let offset = 0;
+    visitParents(node, 'text', (text) => {
+        offsets.set(text, offset);
+        offset += text.value.length;
+    });
+    return offsets;
+}
 /**
  *
  * @param node
@@ -133,19 +624,31 @@ function keywordsPlugin(config) {
  * @param isInlineCode
  * @param config
  * @param language
+ * @param scan - The positions of the code element's words.
+ * @param offset - The offset of the text node in the code element's text.
  */
-function getNodes(node, parent, isInlineCode, config, language) {
+function getNodes(node, parent, isInlineCode, config, language, scan, offset) {
     const { addUsedKeyword, getKeyword } = config;
+    let start = offset;
     return toString(node)
         .split(SPLIT_REGEXP)
         .map((word) => {
+        const wordStart = start;
+        start += word.length;
         const match = word.match(MATCH_KEYWORD_REGEXP);
         if (!match) {
             return { type: 'text', value: word };
         }
         const { key = '', delimiter = '', anchor = '', queryParams = '', } = match.groups;
-        const usedKeyword = `${key}${delimiter}${anchor?.toLowerCase()}`;
-        const rootKeyword = getKeyword?.(key);
+        const position = scan.position(wordStart, wordStart + word.length, key);
+        // Not a reference to a keyword: an object key, a string, a file name and the like
+        if (!position.link) {
+            return { type: 'text', value: word };
+        }
+        // A member after a dot is looked up as a whole `Owner.member`
+        const isMember = position.keyword !== undefined;
+        const usedKeyword = position.keyword ?? `${key}${delimiter}${anchor?.toLowerCase()}`;
+        const rootKeyword = isMember ? undefined : getKeyword?.(key);
         const keyword = getKeyword?.(usedKeyword);
         const isGuideKeyword = key.startsWith('*');
         const isLanguageAllowed = (!keyword?.languages && ALWAYS_ALLOWED_LANGUAGES.includes(language)) ||
@@ -161,7 +664,9 @@ function getNodes(node, parent, isInlineCode, config, language) {
         addUsedKeyword?.(usedKeyword);
         const notFoundGuideKeyword = isGuideKeyword && !keyword;
         const notFoundApiAnchorKeyword = !!rootKeyword && !!anchor && !keyword;
-        if (getKeyword && isInlineCode && (notFoundGuideKeyword || notFoundApiAnchorKeyword)) {
+        // Only inline code that is one keyword reference as a whole fails on a missing one: in code,
+        // `*` and `.` are operators, not keyword syntax.
+        if (getKeyword && scan.whole && (notFoundGuideKeyword || notFoundApiAnchorKeyword)) {
             throw new Error(`Route with keyword "${word}" is missing.`);
         }
         // Convert code tag to a link tag or highlight it with a class
@@ -180,7 +685,7 @@ function getNodes(node, parent, isInlineCode, config, language) {
         }
         // Add link inside the code if it's a link to the API entity
         return keyword
-            ? createLinkNode(isInlineCode ? keyword.title : word, keyword.path, keyword.type, keyword.description)
+            ? createLinkNode(isInlineCode && !isMember ? keyword.title : word, keyword.path, keyword.type, keyword.description)
             : { type: 'text', value: word };
     });
 }
@@ -259,10 +764,10 @@ function addHeadingAnchors(route) {
     });
 }
 
-const languagePrefix = 'language-';
+const languagePrefix$1 = 'language-';
 /**
- * One `@shikijs/rehype` transformer per theme pair in this thread. It loads its highlighter once
- * (every bundled language, the themes and the WASM), where the plain plugin, created again for
+ * One `@shikijs/rehype` transformer per theme pair and languages in this thread. It loads its
+ * highlighter once (every bundled language, the extra ones, the themes and the WASM), where the plain plugin, created again for
  * every document, asks for the highlighter and loads every language and theme into it again on
  * each call. A transformer whose highlighter failed to load is forgotten, so the next document
  * tries again and fails with the same error, as the plain plugin does.
@@ -283,8 +788,8 @@ const highlighters = new Map();
  * loads Shiki once the cache shows that its themes load.
  */
 function cachedShikiPlugin(settings) {
-    const { cache, themes, identity, defaultLanguage } = settings;
-    const id = `${themes.light}\n${themes.dark}`;
+    const { cache, themes, languages, identity, defaultLanguage } = settings;
+    const id = `${themes.light}\n${themes.dark}\n${languages ?? ''}\n${settings.grammars ?? 'all'}`;
     return async (tree) => {
         const blocks = [];
         visit(tree, 'element', (node, index, parent) => {
@@ -295,10 +800,10 @@ function cachedShikiPlugin(settings) {
                 return;
             const classes = head.properties['className'];
             const languageClass = Array.isArray(classes)
-                ? classes.find((item) => typeof item === 'string' && item.startsWith(languagePrefix))
+                ? classes.find((item) => typeof item === 'string' && item.startsWith(languagePrefix$1))
                 : undefined;
             const lang = typeof languageClass === 'string'
-                ? languageClass.slice(languagePrefix.length)
+                ? languageClass.slice(languagePrefix$1.length)
                 : defaultLanguage;
             if (!lang)
                 return;
@@ -308,11 +813,18 @@ function cachedShikiPlugin(settings) {
             blocks.push({
                 node,
                 parent,
-                key: cache.key({ options: identity, themes, lang, meta, code }),
+                key: cache.key({
+                    options: identity,
+                    themes,
+                    ...(languages === undefined ? {} : { languages }),
+                    lang,
+                    meta,
+                    code,
+                }),
             });
         });
         let highlighter;
-        const load = async () => (highlighter ??= await highlighterFor(id, settings.options));
+        const load = async () => (highlighter ??= await highlighterFor(id, settings.transformer));
         if (cache.loads?.(themes) !== true)
             await load();
         const values = [];
@@ -338,12 +850,12 @@ function cachedShikiPlugin(settings) {
         });
     };
 }
-function highlighterFor(id, options) {
+function highlighterFor(id, transformer) {
     const known = highlighters.get(id);
     if (known)
         return known;
     const created = (async () => {
-        const transform = rehypeShiki(options());
+        const transform = transformer();
         // An empty tree makes the transformer load its highlighter, so that a failure to load is told
         // apart from a block's own failure.
         await transform({ type: 'root', children: [] });
@@ -362,13 +874,14 @@ async function highlight(transform, node) {
     await transform(root);
     return JSON.stringify(root.children);
 }
-/** A cached value as fresh nodes, or undefined when it is not a JSON array of HAST elements. */
+/**
+ * A cached value as fresh nodes, or undefined when it is not a JSON array of HAST elements or of
+ * roots of elements (what `@shikijs/rehype` puts in place of a block).
+ */
 function fragment(value) {
     try {
         const parsed = JSON.parse(value);
-        return Array.isArray(parsed) &&
-            parsed.length > 0 &&
-            parsed.every((item) => isNode(item) && item.type === 'element')
+        return Array.isArray(parsed) && parsed.length > 0 && parsed.every(isReplacement)
             ? parsed
             : undefined;
     }
@@ -376,6 +889,18 @@ function fragment(value) {
         return undefined;
     }
 }
+function isReplacement(value) {
+    if (isNode(value))
+        return value.type === 'element';
+    if (!value || typeof value !== 'object' || Array.isArray(value))
+        return false;
+    const node = value;
+    const children = node['children'];
+    return (node['type'] === 'root' &&
+        Array.isArray(children) &&
+        children.length > 0 &&
+        children.every((child) => isNode(child) && child.type === 'element'));
+}
 function isNode(value) {
     if (!value || typeof value !== 'object' || Array.isArray(value))
         return false;
@@ -563,6 +1088,185 @@ function wrapTablePlugin () {
     };
 }
 
+/**
+ * Loading only the Shiki grammars that code blocks use, with the same result as loading every
+ * bundled grammar.
+ *
+ * `@shikijs/rehype` sets its highlighter up with every bundled grammar, which takes seconds. A
+ * grammar's highlighting depends only on the grammars it can reach: the languages it embeds
+ * (`embeddedLangs`, and `embeddedLangsLazy`, which it uses once they are loaded), the scopes its
+ * rules include, and the grammars that inject into its scopes (`injectTo`, matched by scope
+ * prefix, in registration order). {@link ShikiGrammars.closure} is that set, closed under the
+ * same rules, plus every grammar that shares an injection target with an injector in it, so the
+ * injections of a scope are always registered together. Loaded in the order in which loading every
+ * bundled grammar registers them (the first mention of each name), a closure gives the
+ * highlighter the same grammars, injections and injection order for its languages as loading
+ * everything, whatever else was loaded before: a highlighter only grows by whole closures, and
+ * each scope's grammars are complete when the scope is first loaded.
+ */
+class ShikiGrammars {
+    constructor(registrations) {
+        this.byName = new Map();
+        this.byScope = new Map();
+        this.injectors = new Map();
+        this.order = new Map();
+        this.closures = new Map();
+        this.loaded = new WeakMap();
+        const mention = (name) => {
+            if (!this.order.has(name))
+                this.order.set(name, this.order.size);
+        };
+        for (const registration of registrations) {
+            mention(registration.name);
+            for (const embedded of registration.embeddedLangs ?? [])
+                mention(embedded);
+            if (this.byScope.has(registration.scopeName))
+                continue;
+            this.byScope.set(registration.scopeName, registration);
+            this.byName.set(registration.name, registration);
+            for (const alias of registration.aliases ?? [])
+                this.byName.set(alias, registration);
+            for (const target of registration.injectTo ?? []) {
+                const list = this.injectors.get(target) ?? [];
+                list.push(registration);
+                this.injectors.set(target, list);
+            }
+        }
+    }
+    /**
+     * The bundled grammars, in the order `@shikijs/rehype` registers them: every bundled language
+     * name, each with the registrations of its module.
+     */
+    static async create() {
+        const modules = await Promise.all(Object.keys(bundledLanguages).map((name) => bundledLanguages[name]()));
+        return new ShikiGrammars(modules.flatMap((module) => module.default));
+    }
+    /**
+     * The grammars that a block of `language` can reach, in registration order; empty for a
+     * language that no bundled grammar names (it falls back to plain text, as before).
+     * @param language
+     */
+    closure(language) {
+        const known = this.closures.get(language);
+        if (known)
+            return known;
+        const set = new Set();
+        const queue = [this.byName.get(language)];
+        while (queue.length) {
+            const registration = queue.pop();
+            if (!registration || set.has(registration))
+                continue;
+            set.add(registration);
+            for (const name of [
+                ...(registration.embeddedLangs ?? []),
+                ...(registration.embeddedLangsLazy ?? []),
+            ])
+                queue.push(this.byName.get(name));
+            for (const scope of includedScopes(registration))
+                queue.push(this.byScope.get(scope));
+            for (const prefix of prefixes(registration.scopeName))
+                queue.push(...(this.injectors.get(prefix) ?? []));
+            for (const target of registration.injectTo ?? [])
+                queue.push(...(this.injectors.get(target) ?? []));
+        }
+        const closure = [...set].sort((left, right) => this.order.get(left.name) - this.order.get(right.name));
+        this.closures.set(language, closure);
+        return closure;
+    }
+    /**
+     * Loads the closures of `languages` that `highlighter` does not hold yet.
+     * @param highlighter
+     * @param languages
+     */
+    load(highlighter, languages) {
+        let loaded = this.loaded.get(highlighter);
+        if (!loaded)
+            this.loaded.set(highlighter, (loaded = new Set()));
+        const missing = new Set();
+        for (const language of languages)
+            for (const registration of this.closure(language))
+                if (!loaded.has(registration.name))
+                    missing.add(registration);
+        if (!missing.size)
+            return;
+        const batch = [...missing].sort((left, right) => this.order.get(left.name) - this.order.get(right.name));
+        highlighter.loadLanguageSync(batch);
+        for (const registration of batch)
+            loaded.add(registration.name);
+    }
+}
+let grammars;
+/** The bundled grammars of this thread, read once. */
+function shikiGrammars() {
+    grammars ??= ShikiGrammars.create().catch((error) => {
+        grammars = undefined;
+        throw error;
+    });
+    return grammars;
+}
+/**
+ * A highlighter with the given themes and no language: {@link ShikiGrammars.load} adds them.
+ * @param themes
+ */
+function createGrammarlessHighlighter(themes) {
+    return createHighlighter({ themes, langs: [] });
+}
+const languagePrefix = 'language-';
+/**
+ * The language of every block `@shikijs/rehype` highlights in `tree` (a `pre` whose first child is
+ * a `code` element with properties): its `language-*` class, or `defaultLanguage`.
+ * @param tree
+ * @param defaultLanguage
+ */
+function blockLanguages(tree, defaultLanguage) {
+    const languages = new Set();
+    visit(tree, 'element', (node) => {
+        if (node.tagName !== 'pre')
+            return;
+        const head = node.children[0];
+        if (!head || head.type !== 'element' || head.tagName !== 'code' || !head.properties)
+            return;
+        const classes = head.properties['className'];
+        const languageClass = Array.isArray(classes)
+            ? classes.find((item) => typeof item === 'string' && item.startsWith(languagePrefix))
+            : undefined;
+        languages.add(typeof languageClass === 'string'
+            ? languageClass.slice(languagePrefix.length)
+            : defaultLanguage);
+    });
+    return languages;
+}
+/**
+ * The scopes that a grammar's rules include from other grammars (`include: "source.x#rule"`).
+ * @param registration
+ */
+function includedScopes(registration) {
+    const scopes = new Set();
+    const walk = (value) => {
+        if (Array.isArray(value))
+            value.forEach(walk);
+        else if (value && typeof value === 'object')
+            for (const [key, item] of Object.entries(value)) {
+                if (key === 'include' && typeof item === 'string') {
+                    if (!item.startsWith('#') && !item.startsWith('$'))
+                        scopes.add(item.split('#')[0]);
+                }
+                else
+                    walk(item);
+            }
+    };
+    walk(registration);
+    return scopes;
+}
+/**
+ * `a`, `a.b` and `a.b.c` for `a.b.c`: the scopes an injection target matches.
+ * @param scope
+ */
+function prefixes(scope) {
+    const parts = scope.split('.');
+    return parts.map((_, index) => parts.slice(0, index + 1).join('.'));
+}
+
 /**
  *
  * @param html
@@ -574,6 +1278,8 @@ async function processHtml(html, config) {
         light: config.lightTheme ?? 'github-light',
         dark: config.darkTheme ?? 'ayu-dark',
     };
+    const langs = config.langs?.length ? config.langs : undefined;
+    const used = !langs && config.grammars === 'used';
     try {
         const content = await unified()
             .use(rehypeParse, { fragment: true })
@@ -588,13 +1294,23 @@ async function processHtml(html, config) {
                     {
                         cache: config.highlight,
                         themes,
+                        ...(langs ? { languages: languagesId(langs) } : {}),
+                        ...(used ? { grammars: 'used' } : {}),
                         identity: HIGHLIGHT_IDENTITY,
                         defaultLanguage: DEFAULT_LANGUAGE,
-                        options: () => shikiOptions(themes),
+                        transformer: () => langs
+                            ? withLanguages(themes, langs)
+                            : used
+                                ? withUsedGrammars(themes)
+                                : rehypeShiki(shikiOptions(themes)),
                     },
                 ],
             ]
-            : [[rehypeShiki, shikiOptions(themes)]])
+            : langs
+                ? [[() => withLanguages(themes, langs)]]
+                : used
+                    ? [[() => withUsedGrammars(themes)]]
+                    : [[rehypeShiki, shikiOptions(themes)]])
             .use(highlightCodeLines)
             .use(wrapTablePlugin)
             .use(sluggerPlugin, anchors.add.bind(anchors), config.headings)
@@ -615,7 +1331,7 @@ const DEFAULT_LANGUAGE = 'ts';
  * whenever {@link shikiOptions} or the cached plugin change.
  */
 const HIGHLIGHT_IDENTITY = {
-    format: 1,
+    format: 2,
     defaultLanguage: DEFAULT_LANGUAGE,
     fallbackLanguage: 'text',
     addLanguageClass: true,
@@ -652,6 +1368,92 @@ function shikiOptions(themes) {
 function shikiTheme(name) {
     return name === NG_DOC_SYNTAX_THEME_NAME ? ngDocSyntaxTheme() : name;
 }
+/**
+ * The highlighters with extra languages in this thread, by themes and languages. Each loads every
+ * bundled language and the given ones once; nothing loads into it later, so a block highlights
+ * the same whatever was highlighted before, and documents with other languages (or none) never
+ * see these.
+ */
+const languageHighlighters = new Map();
+const languageIds = new WeakMap();
+/**
+ * The identity of a list of languages: the digest of its JSON.
+ * @param langs
+ */
+function languagesId(langs) {
+    let id = languageIds.get(langs);
+    if (id === undefined) {
+        id = createHash('sha256').update(JSON.stringify(langs)).digest('hex');
+        languageIds.set(langs, id);
+    }
+    return id;
+}
+/**
+ * The `@shikijs/rehype` transformer over the highlighter with these languages, with the options of
+ * the plain plugin. A highlighter that failed to load is forgotten, so that the next document tries
+ * again and fails with the same error.
+ * @param themes - The theme names.
+ * @param themes.light - The light theme.
+ * @param themes.dark - The dark theme.
+ * @param langs - The extra languages.
+ */
+function withLanguages(themes, langs) {
+    const id = `${themes.light}\n${themes.dark}\n${languagesId(langs)}`;
+    return async (tree) => {
+        let highlighter = languageHighlighters.get(id);
+        if (!highlighter) {
+            highlighter = createHighlighter({
+                themes: [shikiTheme(themes.light), shikiTheme(themes.dark)],
+                // Later registrations of a name replace earlier ones, so the given languages win.
+                langs: [...Object.keys(bundledLanguages), ...langs],
+            });
+            languageHighlighters.set(id, highlighter);
+            const created = highlighter;
+            created.catch(() => {
+                if (languageHighlighters.get(id) === created)
+                    languageHighlighters.delete(id);
+            });
+        }
+        const transform = rehypeShikiFromHighlighter(await highlighter, shikiOptions(themes));
+        await transform(tree);
+    };
+}
+/**
+ * The highlighters that load only the grammars code blocks use, by theme pair, in this thread. A
+ * highlighter that failed to load is forgotten, so that the next document tries again and fails
+ * with the same error.
+ */
+const usedHighlighters = new Map();
+/**
+ * The `@shikijs/rehype` transformer, with the options of the plain plugin, over this thread's
+ * highlighter for the theme pair, after it has loaded the grammars of the tree's code blocks
+ * (`./shiki-grammars`).
+ * @param themes - The theme names.
+ * @param themes.light - The light theme.
+ * @param themes.dark - The dark theme.
+ */
+function withUsedGrammars(themes) {
+    const id = `${themes.light}\n${themes.dark}`;
+    return async (tree) => {
+        let highlighter = usedHighlighters.get(id);
+        if (!highlighter) {
+            highlighter = createGrammarlessHighlighter([
+                shikiTheme(themes.light),
+                shikiTheme(themes.dark),
+            ]);
+            usedHighlighters.set(id, highlighter);
+            const created = highlighter;
+            created.catch(() => {
+                if (usedHighlighters.get(id) === created)
+                    usedHighlighters.delete(id);
+            });
+        }
+        const [grammars, ready] = await Promise.all([shikiGrammars(), highlighter]);
+        grammars.load(ready, blockLanguages(tree, DEFAULT_LANGUAGE));
+        const transform = rehypeShikiFromHighlighter(ready, shikiOptions(themes));
+        await transform(tree);
+    };
+}
 
 /**
  *