FazBrowse GitHub Viewer | Trending |
URL:
| Home
Tools: [Download Repo ZIP]   [Original HTTPS Page]

tools: add unified plugin changing links for html docs · nodejs/node@da1e5ae · GitHub

/ node Public

Commit da1e5ae

Browse files
Marek Łabuz
authored and
MylesBorins
committed
tools: add unified plugin changing links for html docs
This commit introduces additional stage in the process of generating html docs from markdown files. Plugin transforms links to *.md files in the respository to links to *.html files in the online documentation. Fixes: #28689 PR-URL: #29946 Reviewed-By: Anna Henningsen <anna@addaleax.net>
1 parent 7bc8c85 commit da1e5ae

6 files changed

Lines changed: 81 additions & 1 deletion

File tree

‎Makefile‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -746,7 +746,7 @@ $(LINK_DATA): $(wildcard lib/*.js) tools/doc/apilinks.js
746746
$(call available-node, $(gen-apilink))
747747

748748
out/doc/api/%.json out/doc/api/%.html: doc/api/%.md tools/doc/generate.js \
749-
tools/doc/html.js tools/doc/json.js tools/doc/apilinks.js | $(LINK_DATA)
749+
tools/doc/markdown.js tools/doc/html.js tools/doc/json.js tools/doc/apilinks.js | $(LINK_DATA)
750750
$(call available-node, $(gen-api))
751751

752752
out/doc/api/all.html: $(apidocs_html) tools/doc/allhtml.js \

‎test/doctool/test-doctool-html.js‎

Lines changed: 30 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -11,6 +11,7 @@ try {
1111
const assert = require('assert');
1212
const { readFile } = require('fs');
1313
const fixtures = require('../common/fixtures');
14+
const { replaceLinks } = require('../../tools/doc/markdown.js');
1415
const html = require('../../tools/doc/html.js');
1516
const path = require('path');
1617

@@ -22,8 +23,22 @@ const remark2rehype = require('remark-rehype');
2223
const raw = require('rehype-raw');
2324
const htmlStringify = require('rehype-stringify');
2425

26+
// Test links mapper is an object of the following structure:
27+
// {
28+
// [filename]: {
29+
// [link definition identifier]: [url to the linked resource]
30+
// }
31+
// }
32+
const testLinksMapper = {
33+
'foo': {
34+
'command line options': 'cli.html#cli-options',
35+
'web server': 'example.html'
36+
}
37+
};
38+
2539
async function toHTML({ input, filename, nodeVersion }) {
2640
const content = unified()
41+
.use(replaceLinks, { filename, linksMapper: testLinksMapper })
2742
.use(markdown)
2843
.use(html.firstHeader)
2944
.use(html.preprocessText)
@@ -96,6 +111,21 @@ const testData = [
96111
file: fixtures.path('altdocs.md'),
97112
html: '<li><a href="https://nodejs.org/docs/latest-v8.x/api/foo.html">8.x',
98113
},
114+
{
115+
file: fixtures.path('document_with_links.md'),
116+
html: '<h1>Usage and Example<span><a class="mark"' +
117+
'href="#foo_usage_and_example" id="foo_usage_and_example">#</a>' +
118+
'</span></h1><h2>Usage<span><a class="mark" href="#foo_usage"' +
119+
'id="foo_usage">#</a></span></h2><p><code>node \\[options\\] index.js' +
120+
'</code></p><p>Please see the<a href="cli.html#cli-options">' +
121+
'Command Line Options</a>document for more information.</p><h2>' +
122+
'Example<span><a class="mark" href="#foo_example" id="foo_example">' +
123+
'#</a></span></h2><p>An example of a<a href="example.html">' +
124+
'webserver</a>written with Node.js which responds with<code>' +
125+
'\'Hello, World!\'</code>:</p><h2>See also<span><a class="mark"' +
126+
'href="#foo_see_also" id="foo_see_also">#</a></span></h2><p>Check' +
127+
'out also<a href="https://nodejs.org/">this guide</a></p>'
128+
},
99129
];
100130

101131
const spaces = /\s/g;

‎test/fixtures/document_with_links.md‎

Lines changed: 20 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,20 @@
1+
# Usage and Example
2+
3+
## Usage
4+
5+
`node \[options\] index.js`
6+
7+
Please see the [Command Line Options][] document for more information.
8+
9+
## Example
10+
11+
An example of a [web server][] written with Node.js which responds with
12+
`'Hello, World!'`:
13+
14+
## See also
15+
16+
Check out also [this guide][]
17+
18+
[Command Line Options]: cli.md#options
19+
[this guide]: https://nodejs.org/
20+
[web server]: example.md

‎tools/doc/generate.js‎

Lines changed: 3 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -29,6 +29,8 @@ const remark2rehype = require('remark-rehype');
2929
const raw = require('rehype-raw');
3030
const htmlStringify = require('rehype-stringify');
3131

32+
const { replaceLinks } = require('./markdown');
33+
const linksMapper = require('./links-mapper');
3234
const html = require('./html');
3335
const json = require('./json');
3436

@@ -70,6 +72,7 @@ async function main() {
7072
const input = await fs.readFile(filename, 'utf8');
7173

7274
const content = await unified()
75+
.use(replaceLinks, { filename, linksMapper })
7376
.use(markdown)
7477
.use(html.preprocessText)
7578
.use(json.jsonAPI, { filename })

‎tools/doc/links-mapper.json‎

Lines changed: 6 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,6 @@
1+
{
2+
"doc/api/synopsis.md": {
3+
"command line options": "cli.html#cli_command_line_options",
4+
"web server": "http.html"
5+
}
6+
}

‎tools/doc/markdown.js‎

Lines changed: 21 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,21 @@
1+
'use strict';
2+
3+
const visit = require('unist-util-visit');
4+
5+
module.exports = {
6+
replaceLinks
7+
};
8+
9+
function replaceLinks({ filename, linksMapper }) {
10+
return (tree) => {
11+
const fileHtmlUrls = linksMapper[filename];
12+
13+
visit(tree, 'definition', (node) => {
14+
const htmlUrl = fileHtmlUrls && fileHtmlUrls[node.identifier];
15+
16+
if (htmlUrl && typeof htmlUrl === 'string') {
17+
node.url = htmlUrl;
18+
}
19+
});
20+
};
21+
}

0 commit comments

Comments
 (0)
Back | FazBrowse Home | New Git URL