From 3a0131ac40e52d8ff98cfde939553b476df8a387 Mon Sep 17 00:00:00 2001 From: avivkeller Date: Fri, 25 Jul 2025 17:57:31 -0400 Subject: [PATCH 1/5] doc: remove synopsis --- doc/api/index.md | 1 - doc/api/synopsis.md | 94 ------------------------------ test/doctool/test-doctool-html.mjs | 19 +----- tools/doc/generate.mjs | 9 +-- tools/doc/links-mapper.json | 6 -- tools/doc/markdown.mjs | 11 +--- 6 files changed, 7 insertions(+), 133 deletions(-) delete mode 100644 doc/api/synopsis.md delete mode 100644 tools/doc/links-mapper.json diff --git a/doc/api/index.md b/doc/api/index.md index 8db8b8c8806274..7fa74559133fec 100644 --- a/doc/api/index.md +++ b/doc/api/index.md @@ -6,7 +6,6 @@ * [About this documentation](documentation.md) -* [Usage and example](synopsis.md)
diff --git a/doc/api/synopsis.md b/doc/api/synopsis.md deleted file mode 100644 index dda2c5285dc605..00000000000000 --- a/doc/api/synopsis.md +++ /dev/null @@ -1,94 +0,0 @@ -# Usage and example - -## Usage - - - - - -`node [options] [V8 options] [script.js | -e "script" | - ] [arguments]` - -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!'`: - -Commands in this document start with `$` or `>` to replicate how they would -appear in a user's terminal. Do not include the `$` and `>` characters. They are -there to show the start of each command. - -Lines that don't start with `$` or `>` character show the output of the previous -command. - -First, make sure to have downloaded and installed Node.js. See -[Installing Node.js via package manager][] for further install information. - -Now, create an empty project folder called `projects`, then navigate into it. - -Linux and Mac: - -```bash -mkdir ~/projects -cd ~/projects -``` - -Windows CMD: - -```powershell -mkdir %USERPROFILE%\projects -cd %USERPROFILE%\projects -``` - -Windows PowerShell: - -```powershell -mkdir $env:USERPROFILE\projects -cd $env:USERPROFILE\projects -``` - -Next, create a new source file in the `projects` -folder and call it `hello-world.js`. - -Open `hello-world.js` in any preferred text editor and -paste in the following content: - -```js -const http = require('node:http'); - -const hostname = '127.0.0.1'; -const port = 3000; - -const server = http.createServer((req, res) => { - res.statusCode = 200; - res.setHeader('Content-Type', 'text/plain'); - res.end('Hello, World!\n'); -}); - -server.listen(port, hostname, () => { - console.log(`Server running at http://${hostname}:${port}/`); -}); -``` - -Save the file. Then, in the terminal window, to run the `hello-world.js` file, -enter: - -```bash -node hello-world.js -``` - -Output like this should appear in the terminal: - -```console -Server running at http://127.0.0.1:3000/ -``` - -Now, open any preferred web browser and visit `http://127.0.0.1:3000`. - -If the browser displays the string `Hello, World!`, that indicates -the server is working. - -[Command-line options]: cli.md#options -[Installing Node.js via package manager]: https://nodejs.org/en/download/package-manager/ -[web server]: http.md diff --git a/test/doctool/test-doctool-html.mjs b/test/doctool/test-doctool-html.mjs index 08a6af4299c33e..4342b1bf6b08d9 100644 --- a/test/doctool/test-doctool-html.mjs +++ b/test/doctool/test-doctool-html.mjs @@ -5,7 +5,7 @@ import assert from 'assert'; import { readFileSync } from 'fs'; import * as html from '../../tools/doc/html.mjs'; -import { replaceLinks } from '../../tools/doc/markdown.mjs'; +import replaceLinks from '../../tools/doc/markdown.mjs'; import { rehypeRaw, rehypeStringify, @@ -14,22 +14,9 @@ import { unified, } from '../../tools/doc/deps.mjs'; -// 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', - }, -}; - function toHTML({ input, filename, nodeVersion, versions }) { const content = unified() - .use(replaceLinks, { filename, linksMapper: testLinksMapper }) + .use(replaceLinks) .use(remarkParse) .use(html.firstHeader) .use(html.preprocessText, { nodeVersion }) @@ -119,7 +106,7 @@ const testData = [ '

Usage#

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

Please see the' + + '

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

' + '

' + 'Example' + diff --git a/tools/doc/generate.mjs b/tools/doc/generate.mjs index 17beb353083833..46a16a4baa1cb0 100644 --- a/tools/doc/generate.mjs +++ b/tools/doc/generate.mjs @@ -19,7 +19,7 @@ // OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE // USE OR OTHER DEALINGS IN THE SOFTWARE. -import { readFileSync, promises as fs } from 'fs'; +import { promises as fs } from 'fs'; import path from 'path'; import raw from 'rehype-raw'; @@ -32,10 +32,7 @@ import { unified } from 'unified'; import * as html from './html.mjs'; import * as json from './json.mjs'; -import { replaceLinks } from './markdown.mjs'; - -const linksMapperFile = new URL('links-mapper.json', import.meta.url); -const linksMapper = JSON.parse(readFileSync(linksMapperFile, 'utf8')); +import replaceLinks from './markdown.mjs'; // Parse the args. // Don't use nopt or whatever for this. It's simple enough. @@ -84,7 +81,7 @@ async function main() { const content = await unified() .use(frontmatter) - .use(replaceLinks, { filename, linksMapper }) + .use(replaceLinks) .use(markdown) .use(gfm) .use(html.preprocessText, { nodeVersion }) diff --git a/tools/doc/links-mapper.json b/tools/doc/links-mapper.json deleted file mode 100644 index 211ba70c0b5991..00000000000000 --- a/tools/doc/links-mapper.json +++ /dev/null @@ -1,6 +0,0 @@ -{ - "doc/api/synopsis.md": { - "command line options": "cli.html#options", - "web server": "http.html" - } -} diff --git a/tools/doc/markdown.mjs b/tools/doc/markdown.mjs index 6a334585246adc..3fdd69806d019b 100644 --- a/tools/doc/markdown.mjs +++ b/tools/doc/markdown.mjs @@ -2,22 +2,13 @@ import { visit } from 'unist-util-visit'; export const referenceToLocalMdFile = /^(?![+a-z]+:)([^#?]+)\.md(#.+)?$/i; -export function replaceLinks({ filename, linksMapper }) { +export default () => { return (tree) => { - const fileHtmlUrls = linksMapper[filename]; - visit(tree, (node) => { node.url &&= node.url.replace( referenceToLocalMdFile, (_, filename, hash) => `${filename}.html${hash || ''}`, ); }); - visit(tree, 'definition', (node) => { - const htmlUrl = fileHtmlUrls?.[node.identifier]; - - if (htmlUrl && typeof htmlUrl === 'string') { - node.url = htmlUrl; - } - }); }; } From 8b79f7947b4b4087011711b0e57ccf3b53d575cd Mon Sep 17 00:00:00 2001 From: avivkeller Date: Fri, 25 Jul 2025 18:05:37 -0400 Subject: [PATCH 2/5] fixup! --- tools/doc/markdown.mjs | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/tools/doc/markdown.mjs b/tools/doc/markdown.mjs index 3fdd69806d019b..b5294cbb08ac5c 100644 --- a/tools/doc/markdown.mjs +++ b/tools/doc/markdown.mjs @@ -11,4 +11,4 @@ export default () => { ); }); }; -} +}; From 85a00d3c40c00f27f809eca0e6f8350c749d35d4 Mon Sep 17 00:00:00 2001 From: avivkeller Date: Sat, 30 Aug 2025 10:04:44 -0400 Subject: [PATCH 3/5] fixup! --- tools/doc/markdown.mjs | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/tools/doc/markdown.mjs b/tools/doc/markdown.mjs index b5294cbb08ac5c..9f4f8c6572579f 100644 --- a/tools/doc/markdown.mjs +++ b/tools/doc/markdown.mjs @@ -2,7 +2,7 @@ import { visit } from 'unist-util-visit'; export const referenceToLocalMdFile = /^(?![+a-z]+:)([^#?]+)\.md(#.+)?$/i; -export default () => { +export function replaceLinks({ filename, linksMapper }) { return (tree) => { visit(tree, (node) => { node.url &&= node.url.replace( From c849f8e4a54b6e3ad661c31dceef306f2081220a Mon Sep 17 00:00:00 2001 From: avivkeller Date: Sat, 30 Aug 2025 10:04:59 -0400 Subject: [PATCH 4/5] fixup! --- tools/doc/markdown.mjs | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/tools/doc/markdown.mjs b/tools/doc/markdown.mjs index 9f4f8c6572579f..d0a7cf743d63b5 100644 --- a/tools/doc/markdown.mjs +++ b/tools/doc/markdown.mjs @@ -2,7 +2,7 @@ import { visit } from 'unist-util-visit'; export const referenceToLocalMdFile = /^(?![+a-z]+:)([^#?]+)\.md(#.+)?$/i; -export function replaceLinks({ filename, linksMapper }) { +export function replaceLinks() { return (tree) => { visit(tree, (node) => { node.url &&= node.url.replace( From e6e56f8592e859d01a8e162f1228364947623452 Mon Sep 17 00:00:00 2001 From: avivkeller Date: Sun, 12 Oct 2025 11:01:35 -0400 Subject: [PATCH 5/5] fixup! --- test/doctool/test-doctool-html.mjs | 2 +- tools/doc/generate.mjs | 2 +- 2 files changed, 2 insertions(+), 2 deletions(-) diff --git a/test/doctool/test-doctool-html.mjs b/test/doctool/test-doctool-html.mjs index 4342b1bf6b08d9..38d8510849437e 100644 --- a/test/doctool/test-doctool-html.mjs +++ b/test/doctool/test-doctool-html.mjs @@ -5,7 +5,7 @@ import assert from 'assert'; import { readFileSync } from 'fs'; import * as html from '../../tools/doc/html.mjs'; -import replaceLinks from '../../tools/doc/markdown.mjs'; +import { replaceLinks } from '../../tools/doc/markdown.mjs'; import { rehypeRaw, rehypeStringify, diff --git a/tools/doc/generate.mjs b/tools/doc/generate.mjs index 46a16a4baa1cb0..be4653237a901c 100644 --- a/tools/doc/generate.mjs +++ b/tools/doc/generate.mjs @@ -32,7 +32,7 @@ import { unified } from 'unified'; import * as html from './html.mjs'; import * as json from './json.mjs'; -import replaceLinks from './markdown.mjs'; +import { replaceLinks } from './markdown.mjs'; // Parse the args. // Don't use nopt or whatever for this. It's simple enough.