@ng-doc/utils 22.0.0-beta.1 → 22.0.0

package/index.esm.js

@@ -2,7 +2,7 @@ import rehypeMinifyWhitespace from 'rehype-minify-whitespace';
 import rehypeParse from 'rehype-parse';
 import rehypeStringify from 'rehype-stringify';
 import { unified } from 'unified';
-import { KEYWORD_ALLOWED_LANGUAGES, asArray, NG_DOC_ELEMENT } from '@ng-doc/core';
+import { KEYWORD_ALLOWED_LANGUAGES, asArray, NG_DOC_ELEMENT, NG_DOC_SYNTAX_THEME_NAME, ngDocSyntaxTheme } from '@ng-doc/core';
 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';
@@ -20,9 +20,12 @@ import { stringifyEntities as stringifyEntities$1 } from 'stringify-entities';
  * @param html
  */
 function minify(html) {
-  return unified().use(rehypeParse, {
-    fragment: true
-  }).use(rehypeStringify).use(rehypeMinifyWhitespace).processSync(html).toString();
+    return unified()
+        .use(rehypeParse, { fragment: true })
+        .use(rehypeStringify)
+        .use(rehypeMinifyWhitespace)
+        .processSync(html)
+        .toString();
 }
 
 /**
@@ -31,8 +34,8 @@ function minify(html) {
  * @param attr
  */
 function attrValue(node, attr) {
-  const attrKey = attr.toLowerCase();
-  return node.properties?.[attrKey] ? String(node.properties[attrKey]) : undefined;
+    const attrKey = attr.toLowerCase();
+    return node.properties?.[attrKey] ? String(node.properties[attrKey]) : undefined;
 }
 
 /**
@@ -41,8 +44,8 @@ function attrValue(node, attr) {
  * @param cls
  */
 function hasClass(node, cls) {
-  const className = node.properties?.['className']?.toString() ?? '';
-  return !!className && className.includes(cls);
+    const className = node.properties?.['className']?.toString() ?? '';
+    return !!className && className.includes(cls);
 }
 
 /**
@@ -50,7 +53,7 @@ function hasClass(node, cls) {
  * @param ancestors
  */
 function hasLinkAncestor(ancestors) {
-  return ancestors.some(ancestor => isElement$1(ancestor, 'a'));
+    return ancestors.some((ancestor) => isElement$1(ancestor, 'a'));
 }
 
 /**
@@ -59,7 +62,7 @@ function hasLinkAncestor(ancestors) {
  * @param node
  */
 function isCodeBlock(parent, node) {
-  return parent?.type === 'element' && parent.tagName === 'pre' && node.tagName === 'code';
+    return parent?.type === 'element' && parent.tagName === 'pre' && node.tagName === 'code';
 }
 
 /**
@@ -67,7 +70,7 @@ function isCodeBlock(parent, node) {
  * @param node
  */
 function isCodeNode(node) {
-  return isElement$1(node, 'code') || isElement$1(node, 'ng-doc-code');
+    return isElement$1(node, 'code') || isElement$1(node, 'ng-doc-code');
 }
 
 /**
@@ -75,7 +78,7 @@ function isCodeNode(node) {
  * @param node
  */
 function isElement(node) {
-  return node?.type === 'element';
+    return node?.type === 'element';
 }
 
 const HEADINGS = ['h1', 'h2', 'h3', 'h4', 'h5', 'h6'];
@@ -84,7 +87,7 @@ const HEADINGS = ['h1', 'h2', 'h3', 'h4', 'h5', 'h6'];
  * @param node
  */
 function isHeading(node) {
-  return isElement$1(node, HEADINGS);
+    return isElement$1(node, HEADINGS);
 }
 
 const ALWAYS_ALLOWED_LANGUAGES = ['typescript', 'ts', 'angular-ts'];
@@ -96,30 +99,32 @@ const MATCH_KEYWORD_REGEXP = /(?<key>[*\p{L}\w$@-]+)((?<delimiter>[.#])(?<anchor
  * @param config
  */
 function keywordsPlugin(config) {
-  return tree => visitParents(tree, 'element', (node, ancestors) => {
-    if (!isCodeNode(node)) {
-      return;
-    }
-    const isInlineCode = !isElement$1(ancestors[ancestors.length - 1], 'pre');
-    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;
+    return (tree) => visitParents(tree, 'element', (node, ancestors) => {
+        if (!isCodeNode(node)) {
+            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];
-      });
-    }
-  });
+        const isInlineCode = !isElement$1(ancestors[ancestors.length - 1], 'pre');
+        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];
+            });
+        }
+    });
 }
 /**
  *
@@ -130,71 +135,54 @@ function keywordsPlugin(config) {
  * @param language
  */
 function getNodes(node, parent, isInlineCode, config, language) {
-  const {
-    addUsedKeyword,
-    getKeyword
-  } = config;
-  return toString(node).split(SPLIT_REGEXP).map(word => {
-    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 keyword = getKeyword?.(usedKeyword);
-    const isGuideKeyword = key.startsWith('*');
-    const isLanguageAllowed = !keyword?.languages && ALWAYS_ALLOWED_LANGUAGES.includes(language) || !!keyword?.languages?.includes(language);
-    // If language of code block is not allowed, return the word as is
-    if (!isInlineCode && keyword && !isLanguageAllowed) {
-      return {
-        type: 'text',
-        value: word
-      };
-    }
-    // If the keyword is just an asterisk, return the word as is
-    if (isGuideKeyword && key.length === 1) {
-      return {
-        type: 'text',
-        value: word
-      };
-    }
-    addUsedKeyword?.(usedKeyword);
-    const notFoundGuideKeyword = isGuideKeyword && !keyword;
-    const notFoundApiAnchorKeyword = !!rootKeyword && !!anchor && !keyword;
-    if (getKeyword && isInlineCode && (notFoundGuideKeyword || notFoundApiAnchorKeyword)) {
-      throw new Error(`Route with keyword "${word}" is missing.`);
-    }
-    // Convert code tag to a link tag or highlight it with a class
-    if (parent.properties) {
-      if (isInlineCode && keyword?.type === 'link') {
-        parent.tagName = 'a';
-        parent.properties = {
-          href: `${keyword.path}${queryParams ?? ''}`,
-          className: [NG_DOC_ELEMENT]
-        };
-        return {
-          type: 'text',
-          value: keyword.title
-        };
-      } else if (isInlineCode && keyword) {
-        parent.properties['className'] = [NG_DOC_ELEMENT, 'ng-doc-code-with-link'];
-      }
-    }
-    // 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) : {
-      type: 'text',
-      value: word
-    };
-  });
+    const { addUsedKeyword, getKeyword } = config;
+    return toString(node)
+        .split(SPLIT_REGEXP)
+        .map((word) => {
+        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 keyword = getKeyword?.(usedKeyword);
+        const isGuideKeyword = key.startsWith('*');
+        const isLanguageAllowed = (!keyword?.languages && ALWAYS_ALLOWED_LANGUAGES.includes(language)) ||
+            !!keyword?.languages?.includes(language);
+        // If language of code block is not allowed, return the word as is
+        if (!isInlineCode && keyword && !isLanguageAllowed) {
+            return { type: 'text', value: word };
+        }
+        // If the keyword is just an asterisk, return the word as is
+        if (isGuideKeyword && key.length === 1) {
+            return { type: 'text', value: word };
+        }
+        addUsedKeyword?.(usedKeyword);
+        const notFoundGuideKeyword = isGuideKeyword && !keyword;
+        const notFoundApiAnchorKeyword = !!rootKeyword && !!anchor && !keyword;
+        if (getKeyword && isInlineCode && (notFoundGuideKeyword || notFoundApiAnchorKeyword)) {
+            throw new Error(`Route with keyword "${word}" is missing.`);
+        }
+        // Convert code tag to a link tag or highlight it with a class
+        if (parent.properties) {
+            if (isInlineCode && keyword?.type === 'link') {
+                parent.tagName = 'a';
+                parent.properties = {
+                    href: `${keyword.path}${queryParams ?? ''}`,
+                    className: [NG_DOC_ELEMENT],
+                };
+                return { type: 'text', value: keyword.title };
+            }
+            else if (isInlineCode && keyword) {
+                parent.properties['className'] = [NG_DOC_ELEMENT, 'ng-doc-code-with-link'];
+            }
+        }
+        // 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)
+            : { type: 'text', value: word };
+    });
 }
 /**
  *
@@ -204,20 +192,17 @@ function getNodes(node, parent, isInlineCode, config, language) {
  * @param description
  */
 function createLinkNode(text, href, type, description) {
-  return {
-    type: 'element',
-    tagName: 'a',
-    properties: {
-      href: href,
-      class: ['ng-doc-code-anchor', NG_DOC_ELEMENT],
-      'data-link-type': type,
-      ngDocTooltip: description
-    },
-    children: [{
-      type: 'text',
-      value: text
-    }]
-  };
+    return {
+        type: 'element',
+        tagName: 'a',
+        properties: {
+            href: href,
+            class: ['ng-doc-code-anchor', NG_DOC_ELEMENT],
+            'data-link-type': type,
+            ngDocTooltip: description,
+        },
+        children: [{ type: 'text', value: text }],
+    };
 }
 
 /**
@@ -228,24 +213,19 @@ function createLinkNode(text, href, type, description) {
  * @param addUsedKeyword
  */
 async function postProcessHtml(html) {
-  const usedKeywords = new Set();
-  try {
-    const content = await unified().use(rehypeParse, {
-      fragment: true
-    }).use(rehypeStringify).use(keywordsPlugin, {
-      addUsedKeyword: usedKeywords.add.bind(usedKeywords)
-    }).process(html).then(file => file.toString());
-    return {
-      content,
-      usedKeywords: Array.from(usedKeywords)
-    };
-  } catch (error) {
-    return {
-      content: html,
-      usedKeywords: [],
-      error
-    };
-  }
+    const usedKeywords = new Set();
+    try {
+        const content = await unified()
+            .use(rehypeParse, { fragment: true })
+            .use(rehypeStringify)
+            .use(keywordsPlugin, { addUsedKeyword: usedKeywords.add.bind(usedKeywords) })
+            .process(html)
+            .then((file) => file.toString());
+        return { content, usedKeywords: Array.from(usedKeywords) };
+    }
+    catch (error) {
+        return { content: html, usedKeywords: [], error };
+    }
 }
 
 const NO_ANCHOR_CLASS = 'no-anchor';
@@ -255,46 +235,185 @@ const NO_ANCHOR_CLASS = 'no-anchor';
  * @param route
  */
 function addHeadingAnchors(route) {
-  return tree => visit(tree, 'element', node => {
-    if (route && isHeading(node) && node.properties && node.properties['id'] && !hasClass(node, NO_ANCHOR_CLASS)) {
-      node.children.push({
-        type: 'element',
-        tagName: 'ng-doc-heading-anchor',
-        properties: {
-          className: ['ng-doc-anchor'],
-          anchor: node.properties['id']
-        },
-        children: []
-      });
-      node.properties = {
-        ...node.properties,
-        href: route,
-        headingLink: 'true'
-      };
+    return (tree) => visit(tree, 'element', (node) => {
+        if (route &&
+            isHeading(node) &&
+            node.properties &&
+            node.properties['id'] &&
+            !hasClass(node, NO_ANCHOR_CLASS)) {
+            node.children.push({
+                type: 'element',
+                tagName: 'ng-doc-heading-anchor',
+                properties: {
+                    className: ['ng-doc-anchor'],
+                    anchor: node.properties['id'],
+                },
+                children: [],
+            });
+            node.properties = {
+                ...node.properties,
+                href: route,
+                headingLink: 'true',
+            };
+        }
+    });
+}
+
+const languagePrefix = '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
+ * 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.
+ */
+const highlighters = new Map();
+/**
+ * The plain `@shikijs/rehype` plugin, with a cache of its results per block.
+ *
+ * It selects the blocks exactly as the plugin does (`pre` elements whose first child is a `code`
+ * element with properties, with the language of its `language-*` class or the default language)
+ * and leaves the tree unchanged while it keys them. A miss is highlighted by the plugin's own
+ * transformer, on a tree that holds only that block, so it gets exactly the plugin's options,
+ * language fallback, meta parsing and transformers. A failing block throws the plugin's error at
+ * the same block, since a hit cannot fail (the cache holds only blocks that were highlighted), and
+ * nothing is stored for it. Every value is serialized before the tree is changed, and every block
+ * is replaced with nodes parsed from it, so later plugins, which change the tree, never change a
+ * value or a node another block shares. A document whose blocks all hit (or that has none) never
+ * 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}`;
+    return async (tree) => {
+        const blocks = [];
+        visit(tree, 'element', (node, index, parent) => {
+            if (!parent || index == null || 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;
+            const lang = typeof languageClass === 'string'
+                ? languageClass.slice(languagePrefix.length)
+                : defaultLanguage;
+            if (!lang)
+                return;
+            const data = head.data;
+            const meta = data?.meta ?? head.properties['metastring']?.toString() ?? '';
+            const code = toString(head);
+            blocks.push({
+                node,
+                parent,
+                key: cache.key({ options: identity, themes, lang, meta, code }),
+            });
+        });
+        let highlighter;
+        const load = async () => (highlighter ??= await highlighterFor(id, settings.options));
+        if (cache.loads?.(themes) !== true)
+            await load();
+        const values = [];
+        for (const block of blocks) {
+            const cached = cache.get(block.key);
+            const hit = cached === undefined ? undefined : fragment(cached);
+            if (hit && !cache.verify) {
+                values.push(hit);
+                continue;
+            }
+            const fresh = await highlight(await load(), block.node);
+            if (hit && fresh !== cached)
+                cache.mismatch?.(block.key);
+            if (fresh !== cached)
+                cache.set(block.key, fresh);
+            values.push(JSON.parse(fresh));
+        }
+        blocks.forEach((block, position) => {
+            const index = block.parent.children.indexOf(block.node);
+            // A block nested in another block's `pre` was replaced inside that detached element.
+            if (index >= 0)
+                block.parent.children.splice(index, 1, ...values[position]);
+        });
+    };
+}
+function highlighterFor(id, options) {
+    const known = highlighters.get(id);
+    if (known)
+        return known;
+    const created = (async () => {
+        const transform = rehypeShiki(options());
+        // 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: [] });
+        return transform;
+    })();
+    highlighters.set(id, created);
+    created.catch(() => {
+        if (highlighters.get(id) === created)
+            highlighters.delete(id);
+    });
+    return created;
+}
+/** The JSON of the nodes the plugin replaces `node` with. */
+async function highlight(transform, node) {
+    const root = { type: 'root', children: [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. */
+function fragment(value) {
+    try {
+        const parsed = JSON.parse(value);
+        return Array.isArray(parsed) &&
+            parsed.length > 0 &&
+            parsed.every((item) => isNode(item) && item.type === 'element')
+            ? parsed
+            : undefined;
+    }
+    catch {
+        return undefined;
     }
-  });
+}
+function isNode(value) {
+    if (!value || typeof value !== 'object' || Array.isArray(value))
+        return false;
+    const node = value;
+    if (node['type'] === 'text')
+        return typeof node['value'] === 'string';
+    const properties = node['properties'];
+    const children = node['children'];
+    return (node['type'] === 'element' &&
+        typeof node['tagName'] === 'string' &&
+        !!properties &&
+        typeof properties === 'object' &&
+        !Array.isArray(properties) &&
+        Array.isArray(children) &&
+        children.every(isNode));
 }
 
 /**
  * Highlight code lines
  */
 function highlightCodeLines() {
-  return tree => {
-    visit(tree, 'element', (node, _i, parent) => {
-      if (isCodeBlock(parent, node) && parent?.type === 'element') {
-        const highlightedLines = JSON.parse(attrValue(parent, 'highlightedLines') ?? '[]');
-        highlightedLines.length && node.children.filter(isElement).forEach((child, i) => {
-          // eslint-disable-next-line @typescript-eslint/ban-ts-comment
-          // @ts-ignore
-          if (child.properties.class === 'line' && highlightedLines.includes(i + 1)) {
-            // eslint-disable-next-line @typescript-eslint/ban-ts-comment
-            // @ts-ignore
-            child.properties.class = 'line highlighted';
-          }
+    return (tree) => {
+        visit(tree, 'element', (node, _i, parent) => {
+            if (isCodeBlock(parent, node) && parent?.type === 'element') {
+                const highlightedLines = JSON.parse(attrValue(parent, 'highlightedLines') ?? '[]');
+                highlightedLines.length &&
+                    node.children.filter(isElement).forEach((child, i) => {
+                        // eslint-disable-next-line @typescript-eslint/ban-ts-comment
+                        // @ts-ignore
+                        if (child.properties.class === 'line' && highlightedLines.includes(i + 1)) {
+                            // eslint-disable-next-line @typescript-eslint/ban-ts-comment
+                            // @ts-ignore
+                            child.properties.class = 'line highlighted';
+                        }
+                    });
+            }
         });
-      }
-    });
-  };
+    };
 }
 
 /**
@@ -303,15 +422,15 @@ function highlightCodeLines() {
  * @param headings
  */
 function markElementsPlugin() {
-  return tree => {
-    visit(tree, 'element', node => {
-      if (node.properties) {
-        // eslint-disable-next-line @typescript-eslint/ban-ts-comment
-        // @ts-ignore
-        node.properties['className'] = [...asArray(node.properties.className), NG_DOC_ELEMENT];
-      }
-    });
-  };
+    return (tree) => {
+        visit(tree, 'element', (node) => {
+            if (node.properties) {
+                // eslint-disable-next-line @typescript-eslint/ban-ts-comment
+                // @ts-ignore
+                node.properties['className'] = [...asArray(node.properties.className), NG_DOC_ELEMENT];
+            }
+        });
+    };
 }
 
 /**
@@ -320,22 +439,22 @@ function markElementsPlugin() {
  * @param headings
  */
 function mermaidPlugin() {
-  return tree => {
-    visit(tree, 'element', node => {
-      if (node.tagName === 'pre') {
-        const codeNode = node.children[0];
-        if (codeNode.tagName === 'code' && codeNode.properties?.['lang'] === 'mermaid') {
-          node.properties = {
-            className: 'mermaid'
-          };
-          node.children = [{
-            type: 'text',
-            value: toString(codeNode)
-          }];
-        }
-      }
-    });
-  };
+    return (tree) => {
+        visit(tree, 'element', (node) => {
+            if (node.tagName === 'pre') {
+                const codeNode = node.children[0];
+                if (codeNode.tagName === 'code' && codeNode.properties?.['lang'] === 'mermaid') {
+                    node.properties = { className: ['mermaid'] };
+                    node.children = [
+                        {
+                            type: 'text',
+                            value: toString(codeNode),
+                        },
+                    ];
+                }
+            }
+        });
+    };
 }
 
 /**
@@ -345,69 +464,103 @@ function mermaidPlugin() {
  * @param headings
  */
 function sluggerPlugin(addAnchor, headings = ['h1', 'h2', 'h3', 'h4']) {
-  if (!addAnchor) {
-    return () => {};
-  }
-  const slugger = new GithubSlugger();
-  return tree => {
-    slugger.reset();
-    visitParents(tree, 'element', (node, ancestors) => {
-      const scope = getKeywordScope(ancestors);
-      const isHeading = !!headingRank(node) && !hasProperty(node, 'id') && !!headings?.includes(node.tagName.toLowerCase());
-      const attrSlug = attrValue(node, 'dataSlug');
-      const attrSlugTitle = attrValue(node, 'dataSlugTitle');
-      const attrSlugType = attrValue(node, 'dataSlugType');
-      const dataToSlug = isHeading ? toString(node).trim() : attrSlug;
-      if (dataToSlug) {
-        if (node.properties) {
-          const id = attrSlug && attrSlugType === 'member' ? attrSlug : slugger.slug(dataToSlug);
-          node.properties['id'] = id;
-          addAnchor({
-            anchorId: id,
-            anchor: new GithubSlugger().slug(dataToSlug),
-            title: attrSlugTitle || dataToSlug,
-            scope,
-            type: isHeading && attrSlugType !== 'member' || attrSlug && attrSlugType === 'heading' ? 'heading' : 'member'
-          });
-        }
-      }
-    });
-  };
+    if (!addAnchor) {
+        return () => { };
+    }
+    const slugger = new GithubSlugger();
+    return (tree) => {
+        slugger.reset();
+        visitParents(tree, 'element', (node, ancestors) => {
+            const scope = getKeywordScope(ancestors);
+            const isHeading = !!headingRank(node) &&
+                !hasProperty(node, 'id') &&
+                !!headings?.includes(node.tagName.toLowerCase());
+            const attrSlug = attrValue(node, 'dataSlug');
+            const attrSlugTitle = attrValue(node, 'dataSlugTitle');
+            const attrSlugType = attrValue(node, 'dataSlugType');
+            const dataToSlug = isHeading ? toString(node).trim() : attrSlug;
+            if (dataToSlug) {
+                if (node.properties) {
+                    const id = attrSlug && attrSlugType === 'member' ? attrSlug : slugger.slug(dataToSlug);
+                    node.properties['id'] = id;
+                    if (isHeading) {
+                        hideLeadingEmoji(node);
+                    }
+                    addAnchor({
+                        anchorId: id,
+                        anchor: new GithubSlugger().slug(dataToSlug),
+                        title: attrSlugTitle || dataToSlug,
+                        scope,
+                        type: (isHeading && attrSlugType !== 'member') || (attrSlug && attrSlugType === 'heading')
+                            ? 'heading'
+                            : 'member',
+                    });
+                }
+            }
+        });
+    };
+}
+/**
+ * A leading emoji of a heading: one pictograph with its modifiers and joined parts, or a flag.
+ * `libs/builder/helpers/keyword-heading-title.ts` strips the same emoji from keyword titles; keep
+ * both patterns in step.
+ */
+const LEADING_EMOJI = /^(?:\p{Regional_Indicator}{2}|(?:\p{Emoji_Presentation}|\p{Extended_Pictographic}\uFE0F)(?:\p{Emoji_Modifier}|\uFE0F|\u200D\p{Extended_Pictographic}\uFE0F?)*)(?=\s)/u;
+/**
+ * Wraps a decorative leading emoji of a heading in an `aria-hidden` span, so screen readers skip
+ * it. It runs after the heading's id and anchor are taken from the text, so neither changes.
+ * @param heading - The heading element.
+ */
+function hideLeadingEmoji(heading) {
+    const first = heading.children[0];
+    const emoji = first?.type === 'text' ? LEADING_EMOJI.exec(first.value)?.[0] : undefined;
+    if (!emoji) {
+        return;
+    }
+    const rest = { type: 'text', value: first.value.slice(emoji.length) };
+    heading.children.splice(0, 1, {
+        type: 'element',
+        tagName: 'span',
+        properties: { ariaHidden: 'true' },
+        children: [{ type: 'text', value: emoji }],
+    }, rest);
 }
 /**
  *
  * @param ancestors
  */
 function getKeywordScope(ancestors) {
-  const keywordScope = ancestors.find(ancestor => isElement$1(ancestor) && ancestor.tagName === 'ng-doc-keyword-scope');
-  const key = keywordScope?.properties?.['id'];
-  return key ? {
-    key: String(key),
-    title: String(keywordScope?.properties?.['title'])
-  } : undefined;
+    const keywordScope = ancestors.find((ancestor) => isElement$1(ancestor) && ancestor.tagName === 'ng-doc-keyword-scope');
+    const key = keywordScope?.properties?.['id'];
+    return key
+        ? {
+            key: String(key),
+            title: String(keywordScope?.properties?.['title']),
+        }
+        : undefined;
 }
 
 /**
  *
  */
 function wrapTablePlugin () {
-  return tree => {
-    visit(tree, 'element', (node, index, parent) => {
-      const table = node?.tagName === 'table';
-      if (table) {
-        const wrapper = {
-          type: 'element',
-          tagName: 'div',
-          properties: {
-            className: 'ng-doc-table-wrapper'
-          },
-          children: [node]
-        };
-        // @ts-expect-error - parent is a hast node
-        parent.children[index] = wrapper;
-      }
-    });
-  };
+    return (tree) => {
+        visit(tree, 'element', (node, index, parent) => {
+            const table = node?.tagName === 'table';
+            if (table) {
+                const wrapper = {
+                    type: 'element',
+                    tagName: 'div',
+                    properties: {
+                        className: 'ng-doc-table-wrapper',
+                    },
+                    children: [node],
+                };
+                // @ts-expect-error - parent is a hast node
+                parent.children[index] = wrapper;
+            }
+        });
+    };
 }
 
 /**
@@ -416,34 +569,88 @@ function wrapTablePlugin () {
  * @param config
  */
 async function processHtml(html, config) {
-  const anchors = new Set();
-  try {
-    const content = await unified().use(rehypeParse, {
-      fragment: true
-    }).use(rehypeStringify).use(mermaidPlugin)
-    // eslint-disable-next-line @typescript-eslint/ban-ts-comment
-    // @ts-ignore
-    .use(rehypeShiki, {
-      defaultLanguage: 'ts',
-      fallbackLanguage: 'text',
-      addLanguageClass: true,
-      parseMetaString: meta => JSON.parse(meta?.replace(/\\/g, '') || '{}'),
-      themes: {
+    const anchors = new Set();
+    const themes = {
         light: config.lightTheme ?? 'github-light',
-        dark: config.darkTheme ?? 'ayu-dark'
-      }
-    }).use(highlightCodeLines).use(wrapTablePlugin).use(sluggerPlugin, anchors.add.bind(anchors), config.headings).use(rehypeMinifyWhitespace).use(addHeadingAnchors, config.route).use(markElementsPlugin).process(html).then(file => file.toString());
-    return {
-      content,
-      anchors: Array.from(anchors)
+        dark: config.darkTheme ?? 'ayu-dark',
     };
-  } catch (error) {
+    try {
+        const content = await unified()
+            .use(rehypeParse, { fragment: true })
+            .use(rehypeStringify)
+            .use(mermaidPlugin)
+            // eslint-disable-next-line @typescript-eslint/ban-ts-comment
+            // @ts-ignore
+            .use(config.highlight
+            ? [
+                [
+                    cachedShikiPlugin,
+                    {
+                        cache: config.highlight,
+                        themes,
+                        identity: HIGHLIGHT_IDENTITY,
+                        defaultLanguage: DEFAULT_LANGUAGE,
+                        options: () => shikiOptions(themes),
+                    },
+                ],
+            ]
+            : [[rehypeShiki, shikiOptions(themes)]])
+            .use(highlightCodeLines)
+            .use(wrapTablePlugin)
+            .use(sluggerPlugin, anchors.add.bind(anchors), config.headings)
+            .use(rehypeMinifyWhitespace)
+            .use(addHeadingAnchors, config.route)
+            .use(markElementsPlugin)
+            .process(html)
+            .then((file) => file.toString());
+        return { content, anchors: Array.from(anchors) };
+    }
+    catch (error) {
+        return { content: html, anchors: [], error };
+    }
+}
+const DEFAULT_LANGUAGE = 'ts';
+/**
+ * What a cached block's options stand for in its key ({@link NgDocHighlightCache}). Bump `format`
+ * whenever {@link shikiOptions} or the cached plugin change.
+ */
+const HIGHLIGHT_IDENTITY = {
+    format: 1,
+    defaultLanguage: DEFAULT_LANGUAGE,
+    fallbackLanguage: 'text',
+    addLanguageClass: true,
+    parseMetaString: 'json-without-backslashes',
+    tokenizeTimeLimit: 0,
+};
+/**
+ * The options both highlighting paths give `@shikijs/rehype`.
+ * @param themes - The theme names.
+ * @param themes.light - The light theme.
+ * @param themes.dark - The dark theme.
+ */
+function shikiOptions(themes) {
     return {
-      content: html,
-      anchors: [],
-      error
+        defaultLanguage: DEFAULT_LANGUAGE,
+        fallbackLanguage: 'text',
+        addLanguageClass: true,
+        parseMetaString: (meta) => JSON.parse(meta?.replace(/\\/g, '') || '{}'),
+        // Shiki stops tokenizing a line after 500 ms by default and silently colours the rest of
+        // it like the last token. A slow or pre-empted process then renders other HTML than a fast
+        // one, so the build output would depend on machine load. No limit keeps it deterministic.
+        tokenizeTimeLimit: 0,
+        themes: {
+            light: shikiTheme(themes.light),
+            dark: shikiTheme(themes.dark),
+        },
     };
-  }
+}
+/**
+ * A Shiki theme by name. NgDoc's own theme is not bundled with Shiki, so its name resolves to a new
+ * copy of it; any other name is left to Shiki.
+ * @param name - The theme name.
+ */
+function shikiTheme(name) {
+    return name === NG_DOC_SYNTAX_THEME_NAME ? ngDocSyntaxTheme() : name;
 }
 
 /**
@@ -452,19 +659,35 @@ async function processHtml(html, config) {
  * @param headings
  */
 function removeNotIndexableContentPlugin() {
-  return tree => {
-    // eslint-disable-next-line @typescript-eslint/ban-ts-comment
-    // @ts-ignore
-    return filter(tree, {
-      cascade: true
-    }, node => {
-      // eslint-disable-next-line @typescript-eslint/ban-ts-comment
-      // @ts-ignore
-      const preWithCode = node?.tagName === 'pre' && node?.children?.some(isCodeNode);
-      const notIndexable = node?.properties?.['indexable'] === 'false';
-      return !node?.tagName || !preWithCode && !notIndexable;
-    });
-  };
+    return (tree) => {
+        // The slugger wraps a heading's decorative leading emoji in an `aria-hidden` span. It is not
+        // part of the heading's name: indexed, it became a search record of its own, under the
+        // previous section.
+        visit(tree, 'element', (node) => {
+            if (isHeading(node) && isHiddenSpan(node.children[0])) {
+                node.children = node.children.slice(1);
+            }
+        });
+        // eslint-disable-next-line @typescript-eslint/ban-ts-comment
+        // @ts-ignore
+        return filter(tree, { cascade: true }, (node) => {
+            // eslint-disable-next-line @typescript-eslint/ban-ts-comment
+            // @ts-ignore
+            const preWithCode = node?.tagName === 'pre' && node?.children?.some(isCodeNode);
+            const notIndexable = node?.properties?.['indexable'] === 'false';
+            return !node?.tagName || (!preWithCode && !notIndexable);
+        });
+    };
+}
+/**
+ * Whether the node is a span hidden from assistive technology, as the slugger renders the leading
+ * emoji of a heading.
+ * @param node - The first child of a heading.
+ */
+function isHiddenSpan(node) {
+    return (node?.type === 'element' &&
+        node.tagName === 'span' &&
+        node.properties?.['ariaHidden'] === 'true');
 }
 
 /**
@@ -472,7 +695,10 @@ function removeNotIndexableContentPlugin() {
  * @param html
  */
 async function removeNotIndexableContent(html) {
-  return rehype().use(removeNotIndexableContentPlugin).process(html).then(file => file.toString());
+    return rehype()
+        .use(removeNotIndexableContentPlugin)
+        .process(html)
+        .then((file) => file.toString());
 }
 
 /**
@@ -482,14 +708,13 @@ async function removeNotIndexableContent(html) {
  * @param config.getKeyword
  * @param getKeyword
  */
-async function replaceKeywords(html, {
-  getKeyword
-}) {
-  return unified().use(rehypeParse, {
-    fragment: true
-  }).use(rehypeStringify).use(keywordsPlugin, {
-    getKeyword
-  }).process(html).then(file => file.toString());
+async function replaceKeywords(html, { getKeyword }) {
+    return unified()
+        .use(rehypeParse, { fragment: true })
+        .use(rehypeStringify)
+        .use(keywordsPlugin, { getKeyword })
+        .process(html)
+        .then((file) => file.toString());
 }
 
 /**
@@ -497,7 +722,7 @@ async function replaceKeywords(html, {
  * @param content
  */
 function stringifyEntities(content) {
-  return stringifyEntities$1(content);
+    return stringifyEntities$1(content);
 }
 
 export { minify, postProcessHtml, processHtml, removeNotIndexableContent, replaceKeywords, stringifyEntities };