@ng-doc/utils 15.10.0-beta.1

package/README.md

@@ -0,0 +1,38 @@
+[![GitHub Workflow Status][build-shield]][build-url]
+[![NPM][npm-shield]][npm-url]
+[![MIT License][license-shield]][license-url]
+
+<!-- PROJECT LOGO -->
+<br />
+<div align="center">
+  <a href="https://github.com/skoropadas/ng-doc">
+    <img src="https://ng-doc.com/assets/images/ng-doc.svg" alt="Logo" height="100px">
+  </a>
+
+<h3 align="center">NgDoc</h3>
+
+  <p align="center">
+    Create documentation faster than ever!
+    <br />
+    <a href="https://ng-doc.com/"><strong>Explore the docs »</strong></a>
+    <br />
+    <br />
+    <a href="https://github.com/skoropadas/ng-doc/issues">Report Bug</a>
+    ·
+    <a href="https://github.com/skoropadas/ng-doc/issues">Request Feature</a>
+  </p>
+</div>
+
+<!-- ABOUT THE PROJECT -->
+
+## About The Project
+
+This library is a part of NgDoc project, that uses to create documentation
+for Angular projects, please check our [repo](https://github.com/skoropadas/ng-doc) for more details.
+
+[npm-shield]: https://img.shields.io/npm/v/@ng-doc/builder.svg?style=for-the-badge
+[npm-url]: https://www.npmjs.com/package/@ng-doc/builder
+[license-shield]: https://img.shields.io/github/license/skoropadas/ng-doc.svg?style=for-the-badge
+[license-url]: https://github.com/othneildrew/Best-README-Template/blob/master/LICENSE.txt
+[build-shield]: https://img.shields.io/github/actions/workflow/status/skoropadas/ng-doc/release.yml?style=for-the-badge&branch=release
+[build-url]: https://github.com/skoropadas/ng-doc/actions

package/html/helpers/has-class.d.ts

@@ -0,0 +1,7 @@
+import { Element } from 'hast';
+/**
+ *
+ * @param node
+ * @param cls
+ */
+export declare function hasClass(node: Element, cls: string): boolean;

package/html/helpers/has-link-ancestor.d.ts

@@ -0,0 +1,6 @@
+import { Element } from 'hast';
+/**
+ *
+ * @param ancestors
+ */
+export declare function hasLinkAncestor(ancestors: Element[]): boolean;

package/html/helpers/index.d.ts

@@ -0,0 +1,3 @@
+export * from './has-class';
+export * from './has-link-ancestor';
+export * from './is-code-node';

package/html/helpers/is-code-node.d.ts

@@ -0,0 +1,6 @@
+import { Element } from 'hast';
+/**
+ *
+ * @param node
+ */
+export declare function isCodeNode(node: Element): boolean;

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

@@ -0,0 +1,14 @@
+import { NgDocHeading } from '@ng-doc/core';
+import { AddUsedKeyword, GetKeyword } from './plugins/keywords.plugin';
+export interface NgDocHtmlPostProcessorConfig {
+    headings?: NgDocHeading[];
+    route?: string;
+    addUsedKeyword?: AddUsedKeyword;
+    getKeyword?: GetKeyword;
+}
+/**
+ *
+ * @param html
+ * @param config
+ */
+export declare function htmlPostProcessor(html: string, config: NgDocHtmlPostProcessorConfig): Promise<string>;

package/html/plugins/autolink-headings.plugin.d.ts

@@ -0,0 +1,6 @@
+/**
+ *
+ * @param options
+ * @param route
+ */
+export default function autolinkHeading(route?: string): any;

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

@@ -0,0 +1,12 @@
+import { NgDocKeyword } from '@ng-doc/core/interfaces';
+import { Element } from 'hast';
+export type AddUsedKeyword = (keyword: string) => void;
+export type GetKeyword = (keyword: string) => NgDocKeyword | undefined;
+/**
+ *
+ * @param entityStore
+ * @param entity
+ * @param addUsedKeyword
+ * @param getKeyword
+ */
+export default function keywordsPlugin(addUsedKeyword?: AddUsedKeyword, getKeyword?: GetKeyword): (tree: Element) => void;

package/html/plugins/mark-code-blocks.plugin.d.ts

@@ -0,0 +1,9 @@
+/**
+ * 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
+ */
+export default function markCodeBlocksPlugin(): any;

package/html/plugins/mark-elements.plugin.d.ts

@@ -0,0 +1,6 @@
+/**
+ *
+ * @param tree
+ * @param headings
+ */
+export default function markElementsPlugin(): any;

package/html/plugins/remove-not-indexable-content.plugin.d.ts

@@ -0,0 +1,6 @@
+/**
+ *
+ * @param tree
+ * @param headings
+ */
+export default function removeNotIndexableContentPlugin(): any;

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

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

package/html/remove-not-indexable-content.d.ts

@@ -0,0 +1,5 @@
+/**
+ *
+ * @param html
+ */
+export declare function removeNotIndexableContent(html: string): Promise<string>;

package/index.d.ts

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

package/index.js

@@ -0,0 +1,276 @@
+import twig from 'highlight.js/lib/languages/twig';
+import { rehype } from 'rehype';
+import rehypeFormat from 'rehype-format';
+import rehypeHighlight from 'rehype-highlight';
+import rehypeMinifyWhitespace from 'rehype-minify-whitespace';
+import { isElement } from 'hast-util-is-element';
+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 { visitParents, SKIP } from 'unist-util-visit-parents';
+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 { filter } from 'unist-util-filter';
+
+/**
+ *
+ * @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: []
+        }]
+      });
+    }
+  });
+}
+
+const languages = ['typescript'];
+/**
+ *
+ * @param entityStore
+ * @param entity
+ * @param addUsedKeyword
+ * @param getKeyword
+ */
+function keywordsPlugin(addUsedKeyword, 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) {
+          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, 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 getKeyword
+ */
+function getNodes(node, parent, inlineLink, addUsedKeyword, getKeyword) {
+  const KeywordRegExp = /([A-Za-z0-9_.-/*]+)/;
+  return toString(node).split(KeywordRegExp).filter(word => word.length).map(word => {
+    if (KeywordRegExp.test(word)) {
+      addUsedKeyword(word);
+    }
+    const keyword = getKeyword(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
+    };
+  });
+}
+/**
+ *
+ * @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'];
+        }
+      }
+    });
+  };
+}
+
+/**
+ *
+ * @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 tree
+ * @param headings
+ */
+function sluggerPlugin(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())) {
+        if (node.properties) {
+          node.properties['id'] = slugger.slug(toString(node));
+        }
+      }
+    });
+  };
+}
+
+/**
+ *
+ * @param html
+ * @param config
+ */
+async function htmlPostProcessor(html, config) {
+  return rehype().use(rehypeFormat).use(rehypeHighlight, {
+    ignoreMissing: true,
+    languages: {
+      twig
+    }
+  }).use(sluggerPlugin, config.headings).use(rehypeMinifyWhitespace).use(autolinkHeading, config.route).use(keywordsPlugin, config.addUsedKeyword, config.getKeyword).use(markElementsPlugin).use(markCodeBlocksPlugin).process(html).then(file => file.toString());
+}
+
+/**
+ *
+ * @param tree
+ * @param headings
+ */
+function removeNotIndexableContentPlugin() {
+  return tree => {
+    // eslint-disable-next-line @typescript-eslint/ban-ts-comment
+    // @ts-ignore
+    return filter(tree, {
+      cascade: false
+    }, 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;
+    });
+  };
+}
+
+/**
+ *
+ * @param html
+ */
+async function removeNotIndexableContent(html) {
+  return rehype().use(removeNotIndexableContentPlugin).process(html).then(file => file.toString());
+}
+
+export { htmlPostProcessor, removeNotIndexableContent };

package/package.json

@@ -0,0 +1,44 @@
+{
+  "name": "@ng-doc/utils",
+  "version": "15.10.0-beta.1",
+  "type": "module",
+  "dependencies": {
+    "rehype": "^12.0.1",
+    "rehype-format": "^4.0.1",
+    "rehype-highlight": "^6.0.0",
+    "github-slugger": "^2.0.0",
+    "hast-util-has-property": "^2.0.1",
+    "hast-util-heading-rank": "^2.1.1",
+    "hast-util-to-string": "^2.0.0",
+    "unist-util-visit": "^4.1.2",
+    "rehype-minify-whitespace": "^5.0.1",
+    "unist-util-filter": "^4.0.1",
+    "chalk": "^5.2.0"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "module": "./index.js",
+  "main": "./index.js",
+  "types": "./index.d.ts",
+  "keywords": [
+    "angular",
+    "documentation",
+    "generator",
+    "builder",
+    "guides",
+    "api",
+    "demo",
+    "ng-doc"
+  ],
+  "author": "Skoropad Aleksandr <alex@skoropad.dev>",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/skoropadas/ng-doc.git"
+  },
+  "bugs": {
+    "url": "https://github.com/skoropadas/ng-doc/issues"
+  },
+  "homepage": "https://ng-doc.com",
+  "license": "MIT"
+}