From 4c559aac7cff1db3e1288fcfaa4843c60fe16f32 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Marek=20=C5=81abuz?= Date: Sat, 12 Oct 2019 15:00:42 +0200 Subject: [PATCH 1/4] 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: https://github.com/nodejs/node/issues/28689 --- Makefile | 2 +- test/doctool/test-doctool-html.js | 17 +++++++++++ test/fixtures/document_with_links.md | 23 +++++++++++++++ tools/doc/generate.js | 2 ++ tools/doc/markdown.js | 43 ++++++++++++++++++++++++++++ 5 files changed, 86 insertions(+), 1 deletion(-) create mode 100644 test/fixtures/document_with_links.md create mode 100644 tools/doc/markdown.js diff --git a/Makefile b/Makefile index 8d4e6bbe6474b9..8b82fdf91f5b78 100644 --- a/Makefile +++ b/Makefile @@ -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 \ diff --git a/test/doctool/test-doctool-html.js b/test/doctool/test-doctool-html.js index 11b28dc8a2a717..f052990055e224 100644 --- a/test/doctool/test-doctool-html.js +++ b/test/doctool/test-doctool-html.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'); @@ -24,6 +25,7 @@ const htmlStringify = require('rehype-stringify'); async function toHTML({ input, filename, nodeVersion }) { const content = unified() + .use(replaceLinks) .use(markdown) .use(html.firstHeader) .use(html.preprocessText) @@ -96,6 +98,21 @@ const testData = [ file: fixtures.path('altdocs.md'), html: '
  • 8.x', }, + { + file: fixtures.path('document_with_links.md'), + html: '

    Usage and Example#' + + '

    Usage#

    node [options] index.js' + + '

    Please see the' + + 'Command Line Optionsdocument for more information.

    ' + + 'Example' + + '#

    An example of a' + + 'webserverwritten with Node.js which responds with' + + '\'Hello, World!\':

    See also#

    Check' + + 'out alsothis guide

    ' + }, ]; const spaces = /\s/g; diff --git a/test/fixtures/document_with_links.md b/test/fixtures/document_with_links.md new file mode 100644 index 00000000000000..e24c434876d286 --- /dev/null +++ b/test/fixtures/document_with_links.md @@ -0,0 +1,23 @@ +# 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 + +[Command Line Options `.html`]: cli.html#cli-options +[web server `.html`]: example.html diff --git a/tools/doc/generate.js b/tools/doc/generate.js index cd85d5365791ba..468775c623bc12 100644 --- a/tools/doc/generate.js +++ b/tools/doc/generate.js @@ -29,6 +29,7 @@ const remark2rehype = require('remark-rehype'); const raw = require('rehype-raw'); const htmlStringify = require('rehype-stringify'); +const { replaceLinks } = require('./markdown'); const html = require('./html'); const json = require('./json'); @@ -70,6 +71,7 @@ async function main() { const input = await fs.readFile(filename, 'utf8'); const content = await unified() + .use(replaceLinks) .use(markdown) .use(html.preprocessText) .use(json.jsonAPI, { filename }) diff --git a/tools/doc/markdown.js b/tools/doc/markdown.js new file mode 100644 index 00000000000000..2924acceb283ad --- /dev/null +++ b/tools/doc/markdown.js @@ -0,0 +1,43 @@ +// Copyright Joyent, Inc. and other Node contributors. +// +// Permission is hereby granted, free of charge, to any person obtaining a +// copy of this software and associated documentation files (the +// "Software"), to deal in the Software without restriction, including +// without limitation the rights to use, copy, modify, merge, publish, +// distribute, sublicense, and/or sell copies of the Software, and to permit +// persons to whom the Software is furnished to do so, subject to the +// following conditions: +// +// The above copyright notice and this permission notice shall be included +// in all copies or substantial portions of the Software. +// +// THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS +// OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF +// MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN +// NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, +// DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR +// OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE +// USE OR OTHER DEALINGS IN THE SOFTWARE. + +'use strict'; + +const visit = require('unist-util-visit'); + +module.exports = { + replaceLinks +}; + +function replaceLinks() { + return (tree) => { + const linksIdenfitiers = tree.children + .filter((child) => child.type === 'definition') + .map((child) => child.identifier); + + visit(tree, 'linkReference', (node) => { + const htmlLinkIdentifier = `${node.identifier} \`.html\``; + if (linksIdenfitiers.includes(htmlLinkIdentifier)) { + node.identifier = htmlLinkIdentifier; + } + }); + }; +} From 51b7c57970e64908fa281043fdb110cf7c24e3a2 Mon Sep 17 00:00:00 2001 From: Rich Trott Date: Tue, 15 Oct 2019 23:07:47 -0700 Subject: [PATCH 2/4] Update markdown.js --- tools/doc/markdown.js | 21 --------------------- 1 file changed, 21 deletions(-) diff --git a/tools/doc/markdown.js b/tools/doc/markdown.js index 2924acceb283ad..3dbceab40e38dc 100644 --- a/tools/doc/markdown.js +++ b/tools/doc/markdown.js @@ -1,24 +1,3 @@ -// Copyright Joyent, Inc. and other Node contributors. -// -// Permission is hereby granted, free of charge, to any person obtaining a -// copy of this software and associated documentation files (the -// "Software"), to deal in the Software without restriction, including -// without limitation the rights to use, copy, modify, merge, publish, -// distribute, sublicense, and/or sell copies of the Software, and to permit -// persons to whom the Software is furnished to do so, subject to the -// following conditions: -// -// The above copyright notice and this permission notice shall be included -// in all copies or substantial portions of the Software. -// -// THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS -// OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF -// MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN -// NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, -// DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR -// OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE -// USE OR OTHER DEALINGS IN THE SOFTWARE. - 'use strict'; const visit = require('unist-util-visit'); From 401a989758d1925c6a058c2d9cf74c655bc9003c Mon Sep 17 00:00:00 2001 From: Rich Trott Date: Tue, 15 Oct 2019 23:11:18 -0700 Subject: [PATCH 3/4] Update document_with_links.md --- test/fixtures/document_with_links.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/test/fixtures/document_with_links.md b/test/fixtures/document_with_links.md index e24c434876d286..6d40d11a24b1a7 100644 --- a/test/fixtures/document_with_links.md +++ b/test/fixtures/document_with_links.md @@ -2,7 +2,7 @@ ## Usage -`node [options] index.js` +`node \[options\] index.js` Please see the [Command Line Options][] document for more information. From 90277e7ed40910618531b323c0dcc6741bd14b54 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Marek=20=C5=81abuz?= Date: Sat, 19 Oct 2019 11:54:02 +0200 Subject: [PATCH 4/4] refactor replaceLinks plugin to use separate linking json file --- test/doctool/test-doctool-html.js | 17 +++++++++++++++-- test/fixtures/document_with_links.md | 3 --- tools/doc/generate.js | 3 ++- tools/doc/links-mapper.json | 6 ++++++ tools/doc/markdown.js | 15 +++++++-------- 5 files changed, 30 insertions(+), 14 deletions(-) create mode 100644 tools/doc/links-mapper.json diff --git a/test/doctool/test-doctool-html.js b/test/doctool/test-doctool-html.js index f052990055e224..ee8099f8cd8728 100644 --- a/test/doctool/test-doctool-html.js +++ b/test/doctool/test-doctool-html.js @@ -23,9 +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) + .use(replaceLinks, { filename, linksMapper: testLinksMapper }) .use(markdown) .use(html.firstHeader) .use(html.preprocessText) @@ -103,7 +116,7 @@ const testData = [ html: '

    Usage and Example#' + '

    Usage#

    node [options] index.js' + + 'id="foo_usage">#

    node \\[options\\] index.js' + '

    Please see the' + 'Command Line Optionsdocument for more information.

    ' + 'Example' + diff --git a/test/fixtures/document_with_links.md b/test/fixtures/document_with_links.md index 6d40d11a24b1a7..1392029a30ba6a 100644 --- a/test/fixtures/document_with_links.md +++ b/test/fixtures/document_with_links.md @@ -18,6 +18,3 @@ Check out also [this guide][] [Command Line Options]: cli.md#options [this guide]: https://nodejs.org/ [web server]: example.md - -[Command Line Options `.html`]: cli.html#cli-options -[web server `.html`]: example.html diff --git a/tools/doc/generate.js b/tools/doc/generate.js index 468775c623bc12..aac8bfd5e7ba21 100644 --- a/tools/doc/generate.js +++ b/tools/doc/generate.js @@ -30,6 +30,7 @@ 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'); @@ -71,7 +72,7 @@ async function main() { const input = await fs.readFile(filename, 'utf8'); const content = await unified() - .use(replaceLinks) + .use(replaceLinks, { filename, linksMapper }) .use(markdown) .use(html.preprocessText) .use(json.jsonAPI, { filename }) diff --git a/tools/doc/links-mapper.json b/tools/doc/links-mapper.json new file mode 100644 index 00000000000000..158d72c7fe5822 --- /dev/null +++ b/tools/doc/links-mapper.json @@ -0,0 +1,6 @@ +{ + "doc/api/synopsis.md": { + "command line options": "cli.html#cli_command_line_options", + "web server": "http.html" + } +} \ No newline at end of file diff --git a/tools/doc/markdown.js b/tools/doc/markdown.js index 3dbceab40e38dc..97feadbf9990bb 100644 --- a/tools/doc/markdown.js +++ b/tools/doc/markdown.js @@ -6,16 +6,15 @@ module.exports = { replaceLinks }; -function replaceLinks() { +function replaceLinks({ filename, linksMapper }) { return (tree) => { - const linksIdenfitiers = tree.children - .filter((child) => child.type === 'definition') - .map((child) => child.identifier); + const fileHtmlUrls = linksMapper[filename]; - visit(tree, 'linkReference', (node) => { - const htmlLinkIdentifier = `${node.identifier} \`.html\``; - if (linksIdenfitiers.includes(htmlLinkIdentifier)) { - node.identifier = htmlLinkIdentifier; + visit(tree, 'definition', (node) => { + const htmlUrl = fileHtmlUrls && fileHtmlUrls[node.identifier]; + + if (htmlUrl && typeof htmlUrl === 'string') { + node.url = htmlUrl; } }); };