esdoc-plugin-transform-html
ESDoc plugin to transform generated HTML using the Cheerio
API.
Installation
npm install --save-dev esdoc-plugin-transform-html
Usage
Add the esdoc-plugin-transform-html
to your ESDoc config...
... "plugins": "name": "esdoc-plugin-transform-html" "option": ...
Options
The option
property can either be an Object
, String
, or Array<String|Object>
...
The simplest use case is to pass a String
:
... "plugins": "name": "esdoc-plugin-transform-html" "option": "./path/to/transform.js"
Where ./path/to/transform.js
is a path (relative to process.cwd()
) to a javascript module to load.
This javascript module should export a single function. This function will be used to transform the HTML. See the example below.
Optionally, you can pass an array of javascript modules to load:
"name": "esdoc-plugin-transform-html" "option": "./path/to/transform1.js" "./path/to/transform2.js"
For more flexibility, you can pass an Object
or Array<Object>
:
... "plugins": "name": "esdoc-plugin-transform-html" "option": "includes": "manual/**/*" "excludes": "foo.html" "transforms": "./path/to/transform1.js" "./path/to/transform2.js" "includes": "some/glob/**/*" "another/glob/*" "excludes": "foo.html" "transforms": "./path/to/anotherTransform.js" "throwOnError" false
If you provide an Array
, each option object within that array will be applied sequentially.
Available Options
Option | Behavior | Default |
---|---|---|
includes |
An Array<String> or String of glob patterns to include. |
**/* |
excludes |
An Array<String> or String of glob patterns to exclude. |
|
transforms |
An Array<String> or String of relative paths to javascript modules to load. |
|
throwOnError |
If true , will raise any exceptions thrown by the transformer. If false , the exception is only logged. |
true |
Example Transformer
/** * transform function invoked by esdoc-plugin-transform-html * @param * @param * @param * @param * @param * @param * @this */module { // Cheerio's interface is much like jQuery's // See https://cheerio.js.org/ for more details // we could also use `$('title')` here, if for example this function was bound to another context, or you prefer that syntax const $title = this'title'; // get the title but strip off everything after `|` let title = $titletext; // use the h1 for the title on manual and index pages if title = this'h1'text || title; // replace `Index` with `SDK References` on the `indentifiers` page if title = title; // append the `config.title` title += ` | `; // update the title $titletexttitle; // open all external links in a new tab this 'a[href^="http://"]' 'a[href^="https://"]' 'a[href^="//"]' 'a[href][ref*="external"]' ;};