@ng-doc/utils 16.3.6 → 16.4.0

package/html/html-post-processor.d.ts

@@ -1,8 +1,6 @@
-import { NgDocHeading } from '@ng-doc/core';
 import { AddKeyword, GetKeyword } from './plugins/keywords.plugin';
 export interface NgDocHtmlPostProcessorConfig {
-    headings?: NgDocHeading[];
-    route?: string;
+    raiseError: (e: Error) => void;
     addUsedKeyword?: AddKeyword;
     addPotentialKeyword?: AddKeyword;
     getKeyword?: GetKeyword;

package/html/html-processor.d.ts

@@ -0,0 +1,13 @@
+import { NgDocEntityAnchor, NgDocHeading } from '@ng-doc/core';
+export interface NgDocHtmlProcessorConfig {
+    headings?: NgDocHeading[];
+    route?: string;
+    raiseError: (e: Error) => void;
+    addAnchor: (anchor: NgDocEntityAnchor) => void;
+}
+/**
+ *
+ * @param html
+ * @param config
+ */
+export declare function htmlProcessor(html: string, config: NgDocHtmlProcessorConfig): Promise<string>;

package/html/plugins/keywords.plugin.d.ts

@@ -1,13 +1,10 @@
 import { NgDocKeyword } from '@ng-doc/core/interfaces';
 import { Element } from 'hast';
+import { NgDocHtmlPostProcessorConfig } from '../html-post-processor';
 export type AddKeyword = (keyword: string) => void;
 export type GetKeyword = (keyword: string) => NgDocKeyword | undefined;
 /**
  *
- * @param entityStore
- * @param entity
- * @param addUsedKeyword
- * @param addPotentialKeyword
- * @param getKeyword
+ * @param config
  */
-export default function keywordsPlugin(addUsedKeyword?: AddKeyword, addPotentialKeyword?: AddKeyword, getKeyword?: GetKeyword): (tree: Element) => void;
+export default function keywordsPlugin(config: NgDocHtmlPostProcessorConfig): (tree: Element) => void;

package/html/plugins/slugger.plugin.d.ts

@@ -1,8 +1,9 @@
-import { NgDocHeading } from '@ng-doc/core';
+import { NgDocEntityAnchor, NgDocHeading } from '@ng-doc/core';
 import { Root } from 'hast';
 /**
  *
  * @param tree
+ * @param addAnchor
  * @param headings
  */
-export default function sluggerPlugin(headings?: NgDocHeading[]): (tree: Root) => void;
+export default function sluggerPlugin(addAnchor: (anchor: NgDocEntityAnchor) => void, headings?: NgDocHeading[]): (tree: Root) => void;

package/index.d.ts

@@ -1,2 +1,3 @@
 export * from './html/html-post-processor';
+export * from './html/html-processor';
 export * from './html/remove-not-indexable-content';

package/index.js

@@ -1,363 +1,103 @@
-import rehypeFormat from 'rehype-format';
-import rehypeHighlight from 'rehype-highlight';
-import rehypeMinifyWhitespace from 'rehype-minify-whitespace';
-import { visit } from 'unist-util-visit';
 import { NG_DOC_ELEMENT } from '@ng-doc/core/constants/defaults.js';
-import chalk from 'chalk';
 import { toString } from 'hast-util-to-string';
+import { visit } from 'unist-util-visit';
 import { asArray } from '@ng-doc/core/helpers/as-array.js';
-import GithubSlugger from 'github-slugger';
-import { hasProperty } from 'hast-util-has-property';
-import { headingRank } from 'hast-util-heading-rank';
 import proc from 'process';
 import { fileURLToPath } from 'url';
 import path from 'path';
+import rehypeFormat from 'rehype-format';
+import rehypeHighlight from 'rehype-highlight';
+import rehypeMinifyWhitespace from 'rehype-minify-whitespace';
+import GithubSlugger from 'github-slugger';
+import { hasProperty } from 'hast-util-has-property';
+import { headingRank } from 'hast-util-heading-rank';
 import { rehype } from 'rehype';
 import { filter } from 'unist-util-filter';
 
-/*
-Language: Twig
-Requires: xml.js
-Author: Luke Holder <lukemh@gmail.com>
-Description: Twig is a templating language for PHP
-Website: https://twig.symfony.com
-Category: template
-*/
+var unicode$3 = {};
 
-function twig(hljs) {
-  const regex = hljs.regex;
-  const FUNCTION_NAMES = [
-    "absolute_url",
-    "asset|0",
-    "asset_version",
-    "attribute",
-    "block",
-    "constant",
-    "controller|0",
-    "country_timezones",
-    "csrf_token",
-    "cycle",
-    "date",
-    "dump",
-    "expression",
-    "form|0",
-    "form_end",
-    "form_errors",
-    "form_help",
-    "form_label",
-    "form_rest",
-    "form_row",
-    "form_start",
-    "form_widget",
-    "html_classes",
-    "include",
-    "is_granted",
-    "logout_path",
-    "logout_url",
-    "max",
-    "min",
-    "parent",
-    "path|0",
-    "random",
-    "range",
-    "relative_path",
-    "render",
-    "render_esi",
-    "source",
-    "template_from_string",
-    "url|0"
-  ];
+const UNDEFINED_CODE_POINTS = [
+    0xfffe,
+    0xffff,
+    0x1fffe,
+    0x1ffff,
+    0x2fffe,
+    0x2ffff,
+    0x3fffe,
+    0x3ffff,
+    0x4fffe,
+    0x4ffff,
+    0x5fffe,
+    0x5ffff,
+    0x6fffe,
+    0x6ffff,
+    0x7fffe,
+    0x7ffff,
+    0x8fffe,
+    0x8ffff,
+    0x9fffe,
+    0x9ffff,
+    0xafffe,
+    0xaffff,
+    0xbfffe,
+    0xbffff,
+    0xcfffe,
+    0xcffff,
+    0xdfffe,
+    0xdffff,
+    0xefffe,
+    0xeffff,
+    0xffffe,
+    0xfffff,
+    0x10fffe,
+    0x10ffff
+];
 
-  const FILTERS = [
-    "abs",
-    "abbr_class",
-    "abbr_method",
-    "batch",
-    "capitalize",
-    "column",
-    "convert_encoding",
-    "country_name",
-    "currency_name",
-    "currency_symbol",
-    "data_uri",
-    "date",
-    "date_modify",
-    "default",
-    "escape",
-    "file_excerpt",
-    "file_link",
-    "file_relative",
-    "filter",
-    "first",
-    "format",
-    "format_args",
-    "format_args_as_text",
-    "format_currency",
-    "format_date",
-    "format_datetime",
-    "format_file",
-    "format_file_from_text",
-    "format_number",
-    "format_time",
-    "html_to_markdown",
-    "humanize",
-    "inky_to_html",
-    "inline_css",
-    "join",
-    "json_encode",
-    "keys",
-    "language_name",
-    "last",
-    "length",
-    "locale_name",
-    "lower",
-    "map",
-    "markdown",
-    "markdown_to_html",
-    "merge",
-    "nl2br",
-    "number_format",
-    "raw",
-    "reduce",
-    "replace",
-    "reverse",
-    "round",
-    "slice",
-    "slug",
-    "sort",
-    "spaceless",
-    "split",
-    "striptags",
-    "timezone_name",
-    "title",
-    "trans",
-    "transchoice",
-    "trim",
-    "u|0",
-    "upper",
-    "url_encode",
-    "yaml_dump",
-    "yaml_encode"
-  ];
+unicode$3.REPLACEMENT_CHARACTER = '\uFFFD';
 
-  let TAG_NAMES = [
-    "apply",
-    "autoescape",
-    "block",
-    "cache",
-    "deprecated",
-    "do",
-    "embed",
-    "extends",
-    "filter",
-    "flush",
-    "for",
-    "form_theme",
-    "from",
-    "if",
-    "import",
-    "include",
-    "macro",
-    "sandbox",
-    "set",
-    "stopwatch",
-    "trans",
-    "trans_default_domain",
-    "transchoice",
-    "use",
-    "verbatim",
-    "with"
-  ];
+unicode$3.CODE_POINTS = {
+    EOF: -1,
+    NULL: 0x00,
+    TABULATION: 0x09,
+    CARRIAGE_RETURN: 0x0d,
+    LINE_FEED: 0x0a,
+    FORM_FEED: 0x0c,
+    SPACE: 0x20,
+    EXCLAMATION_MARK: 0x21,
+    QUOTATION_MARK: 0x22,
+    NUMBER_SIGN: 0x23,
+    AMPERSAND: 0x26,
+    APOSTROPHE: 0x27,
+    HYPHEN_MINUS: 0x2d,
+    SOLIDUS: 0x2f,
+    DIGIT_0: 0x30,
+    DIGIT_9: 0x39,
+    SEMICOLON: 0x3b,
+    LESS_THAN_SIGN: 0x3c,
+    EQUALS_SIGN: 0x3d,
+    GREATER_THAN_SIGN: 0x3e,
+    QUESTION_MARK: 0x3f,
+    LATIN_CAPITAL_A: 0x41,
+    LATIN_CAPITAL_F: 0x46,
+    LATIN_CAPITAL_X: 0x58,
+    LATIN_CAPITAL_Z: 0x5a,
+    RIGHT_SQUARE_BRACKET: 0x5d,
+    GRAVE_ACCENT: 0x60,
+    LATIN_SMALL_A: 0x61,
+    LATIN_SMALL_F: 0x66,
+    LATIN_SMALL_X: 0x78,
+    LATIN_SMALL_Z: 0x7a,
+    REPLACEMENT_CHARACTER: 0xfffd
+};
 
-  TAG_NAMES = TAG_NAMES.concat(TAG_NAMES.map(t => `end${t}`));
-
-  const STRING = {
-    scope: 'string',
-    variants: [
-      {
-        begin: /'/,
-        end: /'/
-      },
-      {
-        begin: /"/,
-        end: /"/
-      },
-    ]
-  };
-
-  const NUMBER = {
-    scope: "number",
-    match: /\d+/
-  };
-
-  const PARAMS = {
-    begin: /\(/,
-    end: /\)/,
-    excludeBegin: true,
-    excludeEnd: true,
-    contains: [
-      STRING,
-      NUMBER
-    ]
-  };
-
-
-  const FUNCTIONS = {
-    beginKeywords: FUNCTION_NAMES.join(" "),
-    keywords: { name: FUNCTION_NAMES },
-    relevance: 0,
-    contains: [ PARAMS ]
-  };
-
-  const FILTER = {
-    match: /\|(?=[A-Za-z_]+:?)/,
-    beginScope: "punctuation",
-    relevance: 0,
-    contains: [
-      {
-        match: /[A-Za-z_]+:?/,
-        keywords: FILTERS
-      },
-    ]
-  };
-
-  const tagNamed = (tagnames, { relevance }) => {
-    return {
-      beginScope: {
-        1: 'template-tag',
-        3: 'name'
-      },
-      relevance: relevance || 2,
-      endScope: 'template-tag',
-      begin: [
-        /\{%/,
-        /\s*/,
-        regex.either(...tagnames)
-      ],
-      end: /%\}/,
-      keywords: "in",
-      contains: [
-        FILTER,
-        FUNCTIONS,
-        STRING,
-        NUMBER
-      ]
-    };
-  };
-
-  const CUSTOM_TAG_RE = /[a-z_]+/;
-  const TAG = tagNamed(TAG_NAMES, { relevance: 2 });
-  const CUSTOM_TAG = tagNamed([ CUSTOM_TAG_RE ], { relevance: 1 });
-
-  return {
-    name: 'Twig',
-    aliases: [ 'craftcms' ],
-    case_insensitive: true,
-    subLanguage: 'xml',
-    contains: [
-      hljs.COMMENT(/\{#/, /#\}/),
-      TAG,
-      CUSTOM_TAG,
-      {
-        className: 'template-variable',
-        begin: /\{\{/,
-        end: /\}\}/,
-        contains: [
-          'self',
-          FILTER,
-          FUNCTIONS,
-          STRING,
-          NUMBER
-        ]
-      }
-    ]
-  };
-}
-
-var unicode$3 = {};
-
-const UNDEFINED_CODE_POINTS = [
-    0xfffe,
-    0xffff,
-    0x1fffe,
-    0x1ffff,
-    0x2fffe,
-    0x2ffff,
-    0x3fffe,
-    0x3ffff,
-    0x4fffe,
-    0x4ffff,
-    0x5fffe,
-    0x5ffff,
-    0x6fffe,
-    0x6ffff,
-    0x7fffe,
-    0x7ffff,
-    0x8fffe,
-    0x8ffff,
-    0x9fffe,
-    0x9ffff,
-    0xafffe,
-    0xaffff,
-    0xbfffe,
-    0xbffff,
-    0xcfffe,
-    0xcffff,
-    0xdfffe,
-    0xdffff,
-    0xefffe,
-    0xeffff,
-    0xffffe,
-    0xfffff,
-    0x10fffe,
-    0x10ffff
-];
-
-unicode$3.REPLACEMENT_CHARACTER = '\uFFFD';
-
-unicode$3.CODE_POINTS = {
-    EOF: -1,
-    NULL: 0x00,
-    TABULATION: 0x09,
-    CARRIAGE_RETURN: 0x0d,
-    LINE_FEED: 0x0a,
-    FORM_FEED: 0x0c,
-    SPACE: 0x20,
-    EXCLAMATION_MARK: 0x21,
-    QUOTATION_MARK: 0x22,
-    NUMBER_SIGN: 0x23,
-    AMPERSAND: 0x26,
-    APOSTROPHE: 0x27,
-    HYPHEN_MINUS: 0x2d,
-    SOLIDUS: 0x2f,
-    DIGIT_0: 0x30,
-    DIGIT_9: 0x39,
-    SEMICOLON: 0x3b,
-    LESS_THAN_SIGN: 0x3c,
-    EQUALS_SIGN: 0x3d,
-    GREATER_THAN_SIGN: 0x3e,
-    QUESTION_MARK: 0x3f,
-    LATIN_CAPITAL_A: 0x41,
-    LATIN_CAPITAL_F: 0x46,
-    LATIN_CAPITAL_X: 0x58,
-    LATIN_CAPITAL_Z: 0x5a,
-    RIGHT_SQUARE_BRACKET: 0x5d,
-    GRAVE_ACCENT: 0x60,
-    LATIN_SMALL_A: 0x61,
-    LATIN_SMALL_F: 0x66,
-    LATIN_SMALL_X: 0x78,
-    LATIN_SMALL_Z: 0x7a,
-    REPLACEMENT_CHARACTER: 0xfffd
-};
-
-unicode$3.CODE_POINT_SEQUENCES = {
-    DASH_DASH_STRING: [0x2d, 0x2d], //--
-    DOCTYPE_STRING: [0x44, 0x4f, 0x43, 0x54, 0x59, 0x50, 0x45], //DOCTYPE
-    CDATA_START_STRING: [0x5b, 0x43, 0x44, 0x41, 0x54, 0x41, 0x5b], //[CDATA[
-    SCRIPT_STRING: [0x73, 0x63, 0x72, 0x69, 0x70, 0x74], //script
-    PUBLIC_STRING: [0x50, 0x55, 0x42, 0x4c, 0x49, 0x43], //PUBLIC
-    SYSTEM_STRING: [0x53, 0x59, 0x53, 0x54, 0x45, 0x4d] //SYSTEM
-};
+unicode$3.CODE_POINT_SEQUENCES = {
+    DASH_DASH_STRING: [0x2d, 0x2d], //--
+    DOCTYPE_STRING: [0x44, 0x4f, 0x43, 0x54, 0x59, 0x50, 0x45], //DOCTYPE
+    CDATA_START_STRING: [0x5b, 0x43, 0x44, 0x41, 0x54, 0x41, 0x5b], //[CDATA[
+    SCRIPT_STRING: [0x73, 0x63, 0x72, 0x69, 0x70, 0x74], //script
+    PUBLIC_STRING: [0x50, 0x55, 0x42, 0x4c, 0x49, 0x43], //PUBLIC
+    SYSTEM_STRING: [0x53, 0x59, 0x53, 0x54, 0x45, 0x4d] //SYSTEM
+};
 
 //Surrogates
 unicode$3.isSurrogate = function(cp) {
@@ -8096,14 +7836,14 @@ function increment() {
 }
 
 var types = /*#__PURE__*/Object.freeze({
-  __proto__: null,
-  boolean: boolean,
-  booleanish: booleanish,
-  overloadedBoolean: overloadedBoolean,
-  number: number,
-  spaceSeparated: spaceSeparated,
-  commaSeparated: commaSeparated,
-  commaOrSpaceSeparated: commaOrSpaceSeparated
+    __proto__: null,
+    boolean: boolean,
+    booleanish: booleanish,
+    overloadedBoolean: overloadedBoolean,
+    number: number,
+    spaceSeparated: spaceSeparated,
+    commaSeparated: commaSeparated,
+    commaOrSpaceSeparated: commaOrSpaceSeparated
 });
 
 /** @type {Array<keyof types>} */
@@ -14622,64 +14362,6 @@ function element(node) {
   )
 }
 
-/**
- *
- * @param node
- * @param cls
- */
-function hasClass(node, cls) {
-  const className = node.properties?.['className']?.toString() ?? '';
-  return !!className && className.includes(cls);
-}
-
-/**
- *
- * @param ancestors
- */
-function hasLinkAncestor(ancestors) {
-  return ancestors.some(ancestor => isElement(ancestor, 'a'));
-}
-
-/**
- *
- * @param node
- */
-function isCodeNode(node) {
-  return isElement(node, 'code') || isElement(node, 'ng-doc-code');
-}
-
-const HEADINGS = ['h1', 'h2', 'h3', 'h4', 'h5', 'h6'];
-const NO_ANCHOR_CLASS = 'no-anchor';
-/**
- *
- * @param options
- * @param route
- */
-function autolinkHeading(route) {
-  return tree => visit(tree, 'element', node => {
-    if (route && isElement(node, HEADINGS) && node.properties && node.properties['id'] && !hasClass(node, NO_ANCHOR_CLASS)) {
-      node.children.push({
-        type: 'element',
-        tagName: 'a',
-        properties: {
-          title: 'Link to heading',
-          className: ['ng-doc-header-link'],
-          href: `${route}#${node.properties['id']}`
-        },
-        children: [{
-          type: 'element',
-          tagName: 'ng-doc-icon',
-          properties: {
-            icon: 'link-2',
-            size: 16
-          },
-          children: []
-        }]
-      });
-    }
-  });
-}
-
 /**
  * @typedef {import('unist').Node} Node
  * @typedef {import('unist').Parent} Parent
@@ -14988,190 +14670,542 @@ const visitParents =
                 return subresult
               }
 
-              offset =
-                typeof subresult[1] === 'number' ? subresult[1] : offset + step;
-            }
-          }
+              offset =
+                typeof subresult[1] === 'number' ? subresult[1] : offset + step;
+            }
+          }
+
+          return result
+        }
+      }
+    }
+  );
+
+/**
+ * Turn a return value into a clean result.
+ *
+ * @param {VisitorResult} value
+ *   Valid return values from visitors.
+ * @returns {ActionTuple}
+ *   Clean result.
+ */
+function toResult(value) {
+  if (Array.isArray(value)) {
+    return value
+  }
+
+  if (typeof value === 'number') {
+    return [CONTINUE, value]
+  }
+
+  return [value]
+}
+
+/**
+ *
+ * @param node
+ * @param cls
+ */
+function hasClass(node, cls) {
+  const className = node.properties?.['className']?.toString() ?? '';
+  return !!className && className.includes(cls);
+}
+
+/**
+ *
+ * @param ancestors
+ */
+function hasLinkAncestor(ancestors) {
+  return ancestors.some(ancestor => isElement(ancestor, 'a'));
+}
+
+/**
+ *
+ * @param node
+ */
+function isCodeNode(node) {
+  return isElement(node, 'code') || isElement(node, 'ng-doc-code');
+}
+
+const languages = ['typescript', 'ts'];
+/**
+ *
+ * @param config
+ */
+function keywordsPlugin(config) {
+  const {
+    addUsedKeyword,
+    addPotentialKeyword,
+    getKeyword
+  } = config;
+  return tree => visitParents(tree, 'element', (node, ancestors) => {
+    if (!isCodeNode(node)) {
+      return;
+    }
+    const isInlineCode = !isElement(ancestors[ancestors.length - 1], 'pre');
+    const lang = node.properties?.['lang']?.toString() || '';
+    if (isInlineCode || languages.includes(lang)) {
+      visitParents(node, 'text', (node, ancestors) => {
+        if (hasLinkAncestor(ancestors) || !getKeyword || !addUsedKeyword || !addPotentialKeyword) {
+          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);
+        // 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];
+      });
+    }
+  });
+}
+/**
+ *
+ * @param node
+ * @param parent
+ * @param inlineLink
+ * @param config
+ */
+function getNodes(node, parent, inlineLink, config) {
+  const KeywordRegExp = /([A-Za-z0-9_\-*]+[.#]?[A-Za-z0-9_\-*$]+)/g;
+  const keywordAnchorRegexp = /^(?<keyword>[A-Za-z0-9_\-*]+)((?<delimiter>[.#])(?<anchor>[A-Za-z0-9_\-*$]+))?$/;
+  const {
+    addUsedKeyword,
+    addPotentialKeyword,
+    getKeyword,
+    raiseError
+  } = config;
+  if (!getKeyword || !addUsedKeyword || !addPotentialKeyword) {
+    throw new Error('Missing config');
+  }
+  return toString(node).split(KeywordRegExp).filter(word => word.length).map(word => {
+    const match = word.match(keywordAnchorRegexp);
+    const formattedWord = match ? `${match.groups?.['keyword']}${match.groups?.['delimiter'] || ''}${match.groups?.['anchor']?.toLowerCase() || ''}` : word;
+    const keyword = getKeyword(formattedWord);
+    const rootKeyword = getKeyword(match?.groups?.['keyword'] || '');
+    if (keywordAnchorRegexp.test(word)) {
+      keyword ? addUsedKeyword(word) : addPotentialKeyword(word);
+    }
+    const notFoundGuideKeyword = /^\*\w+/gm.test(word) && !keyword;
+    const notFoundApiKeyword = !!rootKeyword && !!match?.groups?.['anchor'] && !keyword;
+    if (inlineLink && (notFoundGuideKeyword || notFoundApiKeyword)) {
+      raiseError(new Error(`Route with keyword "${word}" is missing.`));
+    }
+    // Convert code tag to link if it's a link to the page entity
+    if (inlineLink && keyword?.isCodeLink === false) {
+      parent.tagName = 'a';
+      parent.properties = {
+        href: keyword.path
+      };
+      return {
+        type: 'text',
+        value: keyword.title
+      };
+    } else if (inlineLink && keyword && parent.properties) {
+      parent.properties['class'] = [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(inlineLink ? keyword.title : word, keyword.path, keyword.type) : {
+      type: 'text',
+      value: word
+    };
+  });
+}
+/**
+ *
+ * @param text
+ * @param href
+ * @param type
+ * @param anchor
+ */
+function createLinkNode(text, href, type) {
+  return {
+    type: 'element',
+    tagName: 'a',
+    properties: {
+      href: href,
+      class: ['ng-doc-code-anchor', NG_DOC_ELEMENT],
+      'data-link-type': type
+    },
+    children: [{
+      type: 'text',
+      value: text
+    }]
+  };
+}
+
+/**
+ * Add hljs class to `pre` elements that contain `code` elements
+ *
+ * We need this to allow customization of the code block style
+ *
+ * @param tree
+ * @param headings
+ */
+function markCodeBlocksPlugin() {
+  return tree => {
+    visit(tree, 'element', node => {
+      // eslint-disable-next-line @typescript-eslint/ban-ts-comment
+      // @ts-ignore
+      if (node.tagName === 'pre' && node.children?.some(child => child.tagName === 'code')) {
+        if (node.properties) {
+          // eslint-disable-next-line @typescript-eslint/ban-ts-comment
+          // @ts-ignore
+          node.properties['className'] = [...(node.properties?.['className'] ?? []), 'hljs'];
+        }
+      }
+    });
+  };
+}
+
+/**
+ *
+ * @param tree
+ * @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];
+      }
+    });
+  };
+}
+
+/**
+ *
+ * @param html
+ * @param config
+ */
+async function htmlPostProcessor(html, config) {
+  return unified().use(rehypeParse, {
+    fragment: true
+  }).use(rehypeStringify).use(keywordsPlugin, config).use(markElementsPlugin).use(markCodeBlocksPlugin).process(html).then(file => file.toString());
+}
+
+/*
+Language: Twig
+Requires: xml.js
+Author: Luke Holder <lukemh@gmail.com>
+Description: Twig is a templating language for PHP
+Website: https://twig.symfony.com
+Category: template
+*/
+
+function twig(hljs) {
+  const regex = hljs.regex;
+  const FUNCTION_NAMES = [
+    "absolute_url",
+    "asset|0",
+    "asset_version",
+    "attribute",
+    "block",
+    "constant",
+    "controller|0",
+    "country_timezones",
+    "csrf_token",
+    "cycle",
+    "date",
+    "dump",
+    "expression",
+    "form|0",
+    "form_end",
+    "form_errors",
+    "form_help",
+    "form_label",
+    "form_rest",
+    "form_row",
+    "form_start",
+    "form_widget",
+    "html_classes",
+    "include",
+    "is_granted",
+    "logout_path",
+    "logout_url",
+    "max",
+    "min",
+    "parent",
+    "path|0",
+    "random",
+    "range",
+    "relative_path",
+    "render",
+    "render_esi",
+    "source",
+    "template_from_string",
+    "url|0"
+  ];
+
+  const FILTERS = [
+    "abs",
+    "abbr_class",
+    "abbr_method",
+    "batch",
+    "capitalize",
+    "column",
+    "convert_encoding",
+    "country_name",
+    "currency_name",
+    "currency_symbol",
+    "data_uri",
+    "date",
+    "date_modify",
+    "default",
+    "escape",
+    "file_excerpt",
+    "file_link",
+    "file_relative",
+    "filter",
+    "first",
+    "format",
+    "format_args",
+    "format_args_as_text",
+    "format_currency",
+    "format_date",
+    "format_datetime",
+    "format_file",
+    "format_file_from_text",
+    "format_number",
+    "format_time",
+    "html_to_markdown",
+    "humanize",
+    "inky_to_html",
+    "inline_css",
+    "join",
+    "json_encode",
+    "keys",
+    "language_name",
+    "last",
+    "length",
+    "locale_name",
+    "lower",
+    "map",
+    "markdown",
+    "markdown_to_html",
+    "merge",
+    "nl2br",
+    "number_format",
+    "raw",
+    "reduce",
+    "replace",
+    "reverse",
+    "round",
+    "slice",
+    "slug",
+    "sort",
+    "spaceless",
+    "split",
+    "striptags",
+    "timezone_name",
+    "title",
+    "trans",
+    "transchoice",
+    "trim",
+    "u|0",
+    "upper",
+    "url_encode",
+    "yaml_dump",
+    "yaml_encode"
+  ];
+
+  let TAG_NAMES = [
+    "apply",
+    "autoescape",
+    "block",
+    "cache",
+    "deprecated",
+    "do",
+    "embed",
+    "extends",
+    "filter",
+    "flush",
+    "for",
+    "form_theme",
+    "from",
+    "if",
+    "import",
+    "include",
+    "macro",
+    "sandbox",
+    "set",
+    "stopwatch",
+    "trans",
+    "trans_default_domain",
+    "transchoice",
+    "use",
+    "verbatim",
+    "with"
+  ];
+
+  TAG_NAMES = TAG_NAMES.concat(TAG_NAMES.map(t => `end${t}`));
+
+  const STRING = {
+    scope: 'string',
+    variants: [
+      {
+        begin: /'/,
+        end: /'/
+      },
+      {
+        begin: /"/,
+        end: /"/
+      },
+    ]
+  };
 
-          return result
-        }
-      }
-    }
-  );
+  const NUMBER = {
+    scope: "number",
+    match: /\d+/
+  };
 
-/**
- * Turn a return value into a clean result.
- *
- * @param {VisitorResult} value
- *   Valid return values from visitors.
- * @returns {ActionTuple}
- *   Clean result.
- */
-function toResult(value) {
-  if (Array.isArray(value)) {
-    return value
-  }
+  const PARAMS = {
+    begin: /\(/,
+    end: /\)/,
+    excludeBegin: true,
+    excludeEnd: true,
+    contains: [
+      STRING,
+      NUMBER
+    ]
+  };
 
-  if (typeof value === 'number') {
-    return [CONTINUE, value]
-  }
 
-  return [value]
-}
+  const FUNCTIONS = {
+    beginKeywords: FUNCTION_NAMES.join(" "),
+    keywords: { name: FUNCTION_NAMES },
+    relevance: 0,
+    contains: [ PARAMS ]
+  };
 
-const languages = ['typescript', 'ts'];
-/**
- *
- * @param entityStore
- * @param entity
- * @param addUsedKeyword
- * @param addPotentialKeyword
- * @param getKeyword
- */
-function keywordsPlugin(addUsedKeyword, addPotentialKeyword, getKeyword) {
-  return tree => visitParents(tree, 'element', (node, ancestors) => {
-    if (!isCodeNode(node)) {
-      return;
-    }
-    const isInlineCode = !isElement(ancestors[ancestors.length - 1], 'pre');
-    const lang = node.properties?.['lang']?.toString() || '';
-    if (isInlineCode || languages.includes(lang)) {
-      visitParents(node, 'text', (node, ancestors) => {
-        if (hasLinkAncestor(ancestors) || !getKeyword || !addUsedKeyword || !addPotentialKeyword) {
-          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, addUsedKeyword, addPotentialKeyword, getKeyword);
-        // 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];
-      });
-    }
-  });
-}
-/**
- *
- * @param node
- * @param parent
- * @param entityStore
- * @param inlineLink
- * @param e
- * @param addUsedKeyword
- * @param addPotentialKeyword
- * @param getKeyword
- */
-function getNodes(node, parent, inlineLink, addUsedKeyword, addPotentialKeyword, getKeyword) {
-  const KeywordRegExp = /([A-Za-z0-9_.-/*]+)/;
-  return toString(node).split(KeywordRegExp).filter(word => word.length).map(word => {
-    const keyword = getKeyword(word);
-    if (KeywordRegExp.test(word)) {
-      keyword ? addUsedKeyword(word) : addPotentialKeyword(word);
-    }
-    if (inlineLink && /^\*\w+/gm.test(word) && !keyword) {
-      console.log(`\n${chalk.blue('NgDoc:')} ${chalk.yellow(`Keyword "${word}" is missing.`)}`);
-    }
-    // Convert code tag to link if it's a link to the page entity
-    if (inlineLink && keyword?.isCodeLink === false) {
-      parent.tagName = 'a';
-      parent.properties = {
-        href: keyword.path
-      };
-      return {
-        type: 'text',
-        value: keyword.title
-      };
-    } else if (inlineLink && keyword && parent.properties) {
-      parent.properties['class'] = [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(inlineLink ? keyword.title : word, keyword.path, keyword.type) : {
-      type: 'text',
-      value: word
+  const FILTER = {
+    match: /\|(?=[A-Za-z_]+:?)/,
+    beginScope: "punctuation",
+    relevance: 0,
+    contains: [
+      {
+        match: /[A-Za-z_]+:?/,
+        keywords: FILTERS
+      },
+    ]
+  };
+
+  const tagNamed = (tagnames, { relevance }) => {
+    return {
+      beginScope: {
+        1: 'template-tag',
+        3: 'name'
+      },
+      relevance: relevance || 2,
+      endScope: 'template-tag',
+      begin: [
+        /\{%/,
+        /\s*/,
+        regex.either(...tagnames)
+      ],
+      end: /%\}/,
+      keywords: "in",
+      contains: [
+        FILTER,
+        FUNCTIONS,
+        STRING,
+        NUMBER
+      ]
     };
-  });
-}
-/**
- *
- * @param text
- * @param href
- * @param type
- */
-function createLinkNode(text, href, type) {
-  return {
-    type: 'element',
-    tagName: 'a',
-    properties: {
-      href: href,
-      class: ['ng-doc-code-anchor', NG_DOC_ELEMENT],
-      'data-link-type': type
-    },
-    children: [{
-      type: 'text',
-      value: text
-    }]
   };
-}
 
-/**
- * Add hljs class to `pre` elements that contain `code` elements
- *
- * We need this to allow customization of the code block style
- *
- * @param tree
- * @param headings
- */
-function markCodeBlocksPlugin() {
-  return tree => {
-    visit(tree, 'element', node => {
-      // eslint-disable-next-line @typescript-eslint/ban-ts-comment
-      // @ts-ignore
-      if (node.tagName === 'pre' && node.children?.some(child => child.tagName === 'code')) {
-        if (node.properties) {
-          // eslint-disable-next-line @typescript-eslint/ban-ts-comment
-          // @ts-ignore
-          node.properties['className'] = [...(node.properties?.['className'] ?? []), 'hljs'];
-        }
+  const CUSTOM_TAG_RE = /[a-z_]+/;
+  const TAG = tagNamed(TAG_NAMES, { relevance: 2 });
+  const CUSTOM_TAG = tagNamed([ CUSTOM_TAG_RE ], { relevance: 1 });
+
+  return {
+    name: 'Twig',
+    aliases: [ 'craftcms' ],
+    case_insensitive: true,
+    subLanguage: 'xml',
+    contains: [
+      hljs.COMMENT(/\{#/, /#\}/),
+      TAG,
+      CUSTOM_TAG,
+      {
+        className: 'template-variable',
+        begin: /\{\{/,
+        end: /\}\}/,
+        contains: [
+          'self',
+          FILTER,
+          FUNCTIONS,
+          STRING,
+          NUMBER
+        ]
       }
-    });
+    ]
   };
 }
 
+const HEADINGS = ['h1', 'h2', 'h3', 'h4', 'h5', 'h6'];
+const NO_ANCHOR_CLASS = 'no-anchor';
 /**
  *
- * @param tree
- * @param headings
+ * @param options
+ * @param route
  */
-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];
-      }
-    });
-  };
+function autolinkHeading(route) {
+  return tree => visit(tree, 'element', node => {
+    if (route && isElement(node, HEADINGS) && node.properties && node.properties['id'] && !hasClass(node, NO_ANCHOR_CLASS)) {
+      node.children.push({
+        type: 'element',
+        tagName: 'a',
+        properties: {
+          title: 'Link to heading',
+          className: ['ng-doc-header-link'],
+          href: `${route}#${node.properties['id']}`
+        },
+        children: [{
+          type: 'element',
+          tagName: 'ng-doc-icon',
+          properties: {
+            icon: 'link-2',
+            size: 16
+          },
+          children: []
+        }]
+      });
+    }
+  });
 }
 
 /**
  *
  * @param tree
+ * @param addAnchor
  * @param headings
  */
-function sluggerPlugin(headings) {
+function sluggerPlugin(addAnchor, headings) {
   headings = headings || ['h1', 'h2', 'h3', 'h4'];
   const slugger = new GithubSlugger();
   return tree => {
     slugger.reset();
     visit(tree, 'element', node => {
-      if (headingRank(node) && !hasProperty(node, 'id') && headings?.includes(node.tagName.toLowerCase())) {
+      const isHeading = headingRank(node) && !hasProperty(node, 'id') && headings?.includes(node.tagName.toLowerCase());
+      const isSlugAttribute = hasProperty(node, 'dataslug');
+      const dataToSlug = isHeading ? toString(node) : isSlugAttribute ? String(node.properties?.['dataslug']) : undefined;
+      if (dataToSlug) {
         if (node.properties) {
-          node.properties['id'] = slugger.slug(toString(node));
+          const slug = slugger.slug(dataToSlug);
+          const slugTitle = node.properties?.['dataslugtitle'] ? String(node.properties['dataslugtitle']) : undefined;
+          node.properties['id'] = slug;
+          addAnchor({
+            anchor: slug,
+            title: slugTitle || dataToSlug,
+            type: isHeading && node.properties?.['dataslugtype'] !== 'member' || isSlugAttribute && node.properties?.['dataslugtype'] === 'heading' ? 'heading' : 'member'
+          });
         }
       }
     });
@@ -15183,7 +15217,7 @@ function sluggerPlugin(headings) {
  * @param html
  * @param config
  */
-async function htmlPostProcessor(html, config) {
+async function htmlProcessor(html, config) {
   return unified().use(rehypeParse, {
     fragment: true
   }).use(rehypeStringify).use(rehypeFormat).use(rehypeHighlight, {
@@ -15191,7 +15225,7 @@ async function htmlPostProcessor(html, config) {
     languages: {
       twig
     }
-  }).use(sluggerPlugin, config.headings).use(rehypeMinifyWhitespace).use(autolinkHeading, config.route).use(keywordsPlugin, config.addUsedKeyword, config.addPotentialKeyword, config.getKeyword).use(markElementsPlugin).use(markCodeBlocksPlugin).process(html).then(file => file.toString());
+  }).use(sluggerPlugin, config.addAnchor, config.headings).use(rehypeMinifyWhitespace).use(autolinkHeading, config.route).process(html).then(file => file.toString());
 }
 
 /**
@@ -15223,4 +15257,4 @@ async function removeNotIndexableContent(html) {
   return rehype().use(removeNotIndexableContentPlugin).process(html).then(file => file.toString());
 }
 
-export { htmlPostProcessor, removeNotIndexableContent };
+export { htmlPostProcessor, htmlProcessor, removeNotIndexableContent };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@ng-doc/utils",
-  "version": "16.3.6",
+  "version": "16.4.0",
   "type": "module",
   "dependencies": {
     "rehype": "12.0.1",