Skip to content
Permalink
Browse files

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>
  • Loading branch information
Marek Łabuz authored and MylesBorins committed Oct 12, 2019
1 parent 7bc8c85 commit da1e5ae1fda06f1b7083644217d4e0a38625b19d
@@ -746,7 +746,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 \
@@ -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');

@@ -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)
@@ -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;
@@ -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
@@ -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');

@@ -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 })
@@ -0,0 +1,6 @@
{
"doc/api/synopsis.md": {
"command line options": "cli.html#cli_command_line_options",
"web server": "http.html"
}
}
@@ -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 da1e5ae

Please sign in to comment.
You can’t perform that action at this time.