Skip to content

Commit

Permalink
tools: add unified plugin changing links for html docs
Browse files Browse the repository at this point in the history
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 <[email protected]>
  • Loading branch information
Marek Łabuz authored and targos committed Dec 5, 2019
1 parent 54cf114 commit 27f7f89
Show file tree
Hide file tree
Showing 6 changed files with 81 additions and 1 deletion.
2 changes: 1 addition & 1 deletion Makefile
Original file line number Diff line number Diff line change
Expand Up @@ -745,7 +745,7 @@ $(LINK_DATA): $(wildcard lib/*.js) tools/doc/apilinks.js
$(call available-node, $(gen-apilink))

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

out/doc/api/all.html: $(apidocs_html) tools/doc/allhtml.js \
Expand Down
30 changes: 30 additions & 0 deletions test/doctool/test-doctool-html.js
Original file line number Diff line number Diff line change
Expand Up @@ -11,6 +11,7 @@ try {
const assert = require('assert');
const { readFile } = require('fs');
const fixtures = require('../common/fixtures');
const { replaceLinks } = require('../../tools/doc/markdown.js');
const html = require('../../tools/doc/html.js');
const path = require('path');

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

// Test links mapper is an object of the following structure:
// {
// [filename]: {
// [link definition identifier]: [url to the linked resource]
// }
// }
const testLinksMapper = {
'foo': {
'command line options': 'cli.html#cli-options',
'web server': 'example.html'
}
};

async function toHTML({ input, filename, nodeVersion }) {
const content = unified()
.use(replaceLinks, { filename, linksMapper: testLinksMapper })
.use(markdown)
.use(html.firstHeader)
.use(html.preprocessText)
Expand Down Expand Up @@ -96,6 +111,21 @@ const testData = [
file: fixtures.path('altdocs.md'),
html: '<li><a href="https://nodejs.org/docs/latest-v8.x/api/foo.html">8.x',
},
{
file: fixtures.path('document_with_links.md'),
html: '<h1>Usage and Example<span><a class="mark"' +
'href="#foo_usage_and_example" id="foo_usage_and_example">#</a>' +
'</span></h1><h2>Usage<span><a class="mark" href="#foo_usage"' +
'id="foo_usage">#</a></span></h2><p><code>node \\[options\\] index.js' +
'</code></p><p>Please see the<a href="cli.html#cli-options">' +
'Command Line Options</a>document for more information.</p><h2>' +
'Example<span><a class="mark" href="#foo_example" id="foo_example">' +
'#</a></span></h2><p>An example of a<a href="example.html">' +
'webserver</a>written with Node.js which responds with<code>' +
'\'Hello, World!\'</code>:</p><h2>See also<span><a class="mark"' +
'href="#foo_see_also" id="foo_see_also">#</a></span></h2><p>Check' +
'out also<a href="https://nodejs.org/">this guide</a></p>'
},
];

const spaces = /\s/g;
Expand Down
20 changes: 20 additions & 0 deletions test/fixtures/document_with_links.md
Original file line number Diff line number Diff line change
@@ -0,0 +1,20 @@
# Usage and Example

## Usage

`node \[options\] index.js`

Please see the [Command Line Options][] document for more information.

## Example

An example of a [web server][] written with Node.js which responds with
`'Hello, World!'`:

## See also

Check out also [this guide][]

[Command Line Options]: cli.md#options
[this guide]: https://nodejs.org/
[web server]: example.md
3 changes: 3 additions & 0 deletions tools/doc/generate.js
Original file line number Diff line number Diff line change
Expand Up @@ -29,6 +29,8 @@ const remark2rehype = require('remark-rehype');
const raw = require('rehype-raw');
const htmlStringify = require('rehype-stringify');

const { replaceLinks } = require('./markdown');
const linksMapper = require('./links-mapper');
const html = require('./html');
const json = require('./json');

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

const content = await unified()
.use(replaceLinks, { filename, linksMapper })
.use(markdown)
.use(html.preprocessText)
.use(json.jsonAPI, { filename })
Expand Down
6 changes: 6 additions & 0 deletions tools/doc/links-mapper.json
Original file line number Diff line number Diff line change
@@ -0,0 +1,6 @@
{
"doc/api/synopsis.md": {
"command line options": "cli.html#cli_command_line_options",
"web server": "http.html"
}
}
21 changes: 21 additions & 0 deletions tools/doc/markdown.js
Original file line number Diff line number Diff line change
@@ -0,0 +1,21 @@
'use strict';

const visit = require('unist-util-visit');

module.exports = {
replaceLinks
};

function replaceLinks({ filename, linksMapper }) {
return (tree) => {
const fileHtmlUrls = linksMapper[filename];

visit(tree, 'definition', (node) => {
const htmlUrl = fileHtmlUrls && fileHtmlUrls[node.identifier];

if (htmlUrl && typeof htmlUrl === 'string') {
node.url = htmlUrl;
}
});
};
}

0 comments on commit 27f7f89

Please sign in to comment.