From f7a6a75a7ccfb6887cb79cb1a1353f02585a088d Mon Sep 17 00:00:00 2001 From: Aviv Keller Date: Thu, 2 Apr 2026 11:36:47 -0400 Subject: [PATCH] feat(docs): use doc-kit 1.3.0 --- .gitignore | 1 - .remarkrc.json | 2 +- components/Metabar/index.jsx | 26 ++-- components/Navigation/index.jsx | 19 ++- components/Sidebar/index.jsx | 64 ++++++-- doc-kit.config.mjs | 7 +- package-lock.json | 127 +++++++++++---- package.json | 4 +- .../asynchronous-flow-control.md | 4 +- .../backpressuring-in-streams.md | 3 - .../discover-javascript-timers.md | 4 +- .../discover-promises-in-nodejs.md | 4 +- .../dont-block-the-event-loop.md | 3 - .../event-loop-timers-and-nexttick.md | 3 - pages/asynchronous-work/how-to-use-streams.md | 4 +- ...-asynchronous-programming-and-callbacks.md | 4 +- .../overview-of-blocking-vs-non-blocking.md | 4 +- .../the-nodejs-event-emitter.md | 4 +- .../understanding-processnexttick.md | 4 +- .../understanding-setimmediate.md | 4 +- ...t-input-from-the-command-line-in-nodejs.md | 4 +- ...-read-environment-variables-from-nodejs.md | 4 +- .../how-to-use-the-nodejs-repl.md | 4 +- ...output-to-the-command-line-using-nodejs.md | 4 +- ...un-nodejs-scripts-from-the-command-line.md | 4 +- pages/diagnostics/debugging.md | 3 - pages/diagnostics/flame-graphs.md | 3 - pages/diagnostics/live-debugging/index.md | 3 - .../live-debugging/using-inspector.md | 3 - pages/diagnostics/memory/index.md | 3 - .../memory/understanding-and-tuning-memory.md | 4 +- pages/diagnostics/memory/using-gc-traces.md | 3 - .../diagnostics/memory/using-heap-profiler.md | 3 - .../diagnostics/memory/using-heap-snapshot.md | 3 - pages/diagnostics/poor-performance/index.md | 3 - .../poor-performance/using-linux-perf.md | 3 - pages/diagnostics/profiling.md | 3 - pages/diagnostics/user-journey.md | 3 - pages/file-system/nodejs-file-paths.md | 4 +- pages/file-system/nodejs-file-stats.md | 4 +- .../file-system/reading-files-with-nodejs.md | 4 +- .../working-with-different-filesystems.md | 3 - ...working-with-file-descriptors-in-nodejs.md | 4 +- .../working-with-folders-in-nodejs.md | 4 +- .../file-system/writing-files-with-nodejs.md | 4 +- ...ferences-between-nodejs-and-the-browser.md | 4 +- .../ecmascript-2015-es6-and-beyond.md | 4 +- ...cript-do-you-need-to-know-to-use-nodejs.md | 4 +- .../getting-started/introduction-to-nodejs.md | 4 +- ...ence-between-development-and-production.md | 4 +- .../nodejs-with-webassembly.md | 4 +- .../the-v8-javascript-engine.md | 4 +- pages/getting-started/userland-migrations.md | 4 +- pages/http/anatomy-of-an-http-transaction.md | 3 - .../http/enterprise-network-configuration.md | 4 +- pages/http/fetch.md | 4 +- pages/http/websocket.md | 4 +- pages/index.md | 4 +- pages/package-management/abi-stability.md | 3 - ...introduction-to-the-npm-package-manager.md | 4 +- .../publishing-a-package.md | 4 +- .../publishing-node-api-modules.md | 3 - pages/security/security-best-practices.md | 4 +- pages/testing/collecting-code-coverage.md | 4 +- pages/testing/introduction.md | 4 +- pages/testing/mocking.md | 4 +- pages/testing/using-test-runner.md | 4 +- pages/typescript/introduction.md | 4 +- pages/typescript/publishing-a-ts-package.md | 4 +- pages/typescript/run-natively.md | 4 +- pages/typescript/run.md | 4 +- pages/typescript/transpile.md | 4 +- scripts/constants.mjs | 40 ----- scripts/generate-component-config.mjs | 124 --------------- scripts/utils.mjs | 144 ------------------ 75 files changed, 269 insertions(+), 526 deletions(-) delete mode 100644 scripts/constants.mjs delete mode 100644 scripts/generate-component-config.mjs delete mode 100644 scripts/utils.mjs diff --git a/.gitignore b/.gitignore index 37e8a3f..9209ef5 100644 --- a/.gitignore +++ b/.gitignore @@ -1,3 +1,2 @@ node_modules out -components/config.json \ No newline at end of file diff --git a/.remarkrc.json b/.remarkrc.json index 0c93434..71f00f7 100644 --- a/.remarkrc.json +++ b/.remarkrc.json @@ -1,3 +1,3 @@ { - "plugins": ["@node-core/remark-lint"] + "plugins": ["remark-frontmatter", "@node-core/remark-lint"] } diff --git a/components/Metabar/index.jsx b/components/Metabar/index.jsx index 681c5bd..60d8a01 100644 --- a/components/Metabar/index.jsx +++ b/components/Metabar/index.jsx @@ -2,19 +2,15 @@ import MetaBar from '@node-core/ui-components/Containers/MetaBar'; import AvatarGroup from '@node-core/ui-components/Common/AvatarGroup'; import GitHubIcon from '@node-core/ui-components/Icons/Social/GitHub'; -import { authors } from '../config.json' with { type: 'json' }; +import { editURL } from '#theme/config'; -/** - * @typedef MetaBarProps - * @property {Array} headings - * @property {string} readingTime - * @property {Array<[string, string]>} viewAs - * @property {string} editThisPage - */ - -/** @param {MetaBarProps} props */ -export default ({ headings = [], readingTime, viewAs = [], editThisPage }) => { - const pageAuthors = authors[editThisPage]; +export default ({ metadata, headings = [], readingTime }) => { + const editThisPage = editURL.replace('{path}', metadata.path); + const authors = metadata.authors?.split(',').map(id => ({ + image: `https://avatars.githubusercontent.com/${id.trim()}`, + url: `https://github.com/${id.trim()}`, + nickname: id, + })); return ( { headings={{ items: headings }} items={{ 'Reading Time': readingTime, - ...(CLIENT && pageAuthors?.length + ...(CLIENT && authors?.length ? { - Authors: ( - - ), + Authors: , } : {}), Contribute: ( diff --git a/components/Navigation/index.jsx b/components/Navigation/index.jsx index 2d58f98..1145153 100644 --- a/components/Navigation/index.jsx +++ b/components/Navigation/index.jsx @@ -7,7 +7,6 @@ import SearchBox from '@node-core/doc-kit/src/generators/web/ui/components/Searc import { useTheme } from '@node-core/doc-kit/src/generators/web/ui/hooks/useTheme.mjs'; import Logo from '#theme/Logo'; -import { topNav } from '../config.json' with { type: 'json' }; /** * NavBar component that displays the headings, search, etc. @@ -19,7 +18,23 @@ export default () => { } */ +const categories = [ + ['getting-started', 'Getting Started'], + ['command-line', 'Command Line'], + ['http', 'HTTP'], + ['file-system', 'File System'], + ['asynchronous-work', 'Asynchronous Work'], + ['typescript', 'TypeScript'], + ['package-management', 'Package Management'], + ['diagnostics', 'Diagnostics'], + ['testing', 'Testing'], + ['security', 'Security'], +]; -/** - * Redirect to a URL - * @param {string} url URL - */ +/** @type {Map>} */ +const byDir = new Map(); +for (const [heading, path] of pages) { + const dir = path.split('/')[1]; + if (!byDir.has(dir)) byDir.set(dir, []); + byDir.get(dir).push({ heading, path }); +} + +/** @param {string} url */ const redirect = url => (window.location.href = url); +const PrefetchLink = props => ; + /** * Sidebar component for MDX documentation with page navigation - * @param {{ pathname: string }} props */ -export default ({ pathname }) => ( - } - title="Navigation" - /> -); +export default ({ metadata }) => { + const { path: currentPath, basename } = metadata; + const pathname = `${basename}.html`; + + const groups = categories.map(([dir, title]) => ({ + groupName: title, + items: byDir.get(dir).map(({ heading, path }) => ({ + label: heading, + link: + currentPath === path ? pathname : `${relative(path, currentPath)}.html`, + })), + })); + + return ( + + ); +}; diff --git a/doc-kit.config.mjs b/doc-kit.config.mjs index 81af158..c221ebc 100644 --- a/doc-kit.config.mjs +++ b/doc-kit.config.mjs @@ -7,13 +7,10 @@ export default { output: 'out', input: ['pages/**/*.md'], }, - 'jsx-ast': { - // TODO(@avivkeller): Hook this up to render at nodejs.org/learn - pageURL: 'https://nodejs.github.io/learn{path}.html', - editURL: 'https://github.com/nodejs/learn/edit/main/pages{path}.md', - }, web: { title: '', + pageURL: 'https://nodejs.org/learn{path}.html', + editURL: 'https://github.com/nodejs/learn/edit/main/pages{path}.md', imports: { ...web.defaultConfiguration.imports, '#theme/Navigation': join( diff --git a/package-lock.json b/package-lock.json index 630a1b4..4b44238 100644 --- a/package-lock.json +++ b/package-lock.json @@ -9,7 +9,7 @@ }, "devDependencies": { "@eslint/js": "^10.0.1", - "@node-core/doc-kit": "1.2.1", + "@node-core/doc-kit": "1.3.0", "@node-core/remark-lint": "^1.3.0", "eslint": "^10.1.0", "eslint-plugin-mdx": "^3.7.0", @@ -17,7 +17,11 @@ "husky": "^9.1.7", "lint-staged": "^16.4.0", "prettier": "^3.8.1", + "remark-frontmatter": "^5.0.0", "typescript-eslint": "^8.57.2" + }, + "engines": { + "node": "24.x" } }, "node_modules/@actions/core": { @@ -821,9 +825,9 @@ } }, "node_modules/@node-core/doc-kit": { - "version": "1.2.1", - "resolved": "https://registry.npmjs.org/@node-core/doc-kit/-/doc-kit-1.2.1.tgz", - "integrity": "sha512-BQxHKolHLEBqHi4UJCeLehTL9ia3uOcjB5Aw0FYqmmYUxDxq0jCDrx9LvHlm0adjoLPwAH+0NJ4xu2dU4V0cPA==", + "version": "1.3.0", + "resolved": "https://registry.npmjs.org/@node-core/doc-kit/-/doc-kit-1.3.0.tgz", + "integrity": "sha512-AVdpEryoIYhhjzrqvQ/VYMCqqVQef9G3YW+EkqVbXBcw02ZqmHH8fE+kq7QcMWUIUavbA4sUm0MWzqNIxEGvOA==", "dev": true, "dependencies": { "@actions/core": "^3.0.0", @@ -842,7 +846,6 @@ "estree-util-visit": "^2.0.0", "github-slugger": "^2.0.0", "glob-parent": "^6.0.2", - "globals": "^17.3.0", "hast-util-to-string": "^3.0.1", "hastscript": "^9.0.1", "lightningcss-wasm": "^1.32.0", @@ -861,7 +864,7 @@ "remark-stringify": "^11.0.0", "rolldown": "^1.0.0-rc.10", "semver": "^7.7.4", - "shiki": "^4.0.0", + "shiki": "^4.0.2", "tinyglobby": "^0.2.15", "unified": "^11.0.5", "unist-builder": "^4.0.0", @@ -2909,29 +2912,6 @@ "hast-util-to-html": "^9.0.5" } }, - "node_modules/@shikijs/engine-javascript": { - "version": "3.23.0", - "resolved": "https://registry.npmjs.org/@shikijs/engine-javascript/-/engine-javascript-3.23.0.tgz", - "integrity": "sha512-aHt9eiGFobmWR5uqJUViySI1bHMqrAgamWE1TYSUoftkAeCCAiGawPMwM+VCadylQtF4V3VNOZ5LmfItH5f3yA==", - "extraneous": true, - "license": "MIT", - "dependencies": { - "@shikijs/types": "3.23.0", - "@shikijs/vscode-textmate": "^10.0.2", - "oniguruma-to-es": "^4.3.4" - } - }, - "node_modules/@shikijs/engine-oniguruma": { - "version": "3.23.0", - "resolved": "https://registry.npmjs.org/@shikijs/engine-oniguruma/-/engine-oniguruma-3.23.0.tgz", - "integrity": "sha512-1nWINwKXxKKLqPibT5f4pAFLej9oZzQTsby8942OTlsJzOBZ0MWKiwzMsd+jhzu8YPCHAswGnnN1YtQfirL35g==", - "extraneous": true, - "license": "MIT", - "dependencies": { - "@shikijs/types": "3.23.0", - "@shikijs/vscode-textmate": "^10.0.2" - } - }, "node_modules/@shikijs/langs": { "version": "4.0.2", "resolved": "https://registry.npmjs.org/@shikijs/langs/-/langs-4.0.2.tgz", @@ -4875,6 +4855,20 @@ "dev": true, "license": "MIT" }, + "node_modules/fault": { + "version": "2.0.1", + "resolved": "https://registry.npmjs.org/fault/-/fault-2.0.1.tgz", + "integrity": "sha512-WtySTkS4OKev5JtpHXnib4Gxiurzh5NCGvWrFaZ34m6JehfTUhKZvn9njTfw48t6JumVQOmrKqpmGcdwxnhqBQ==", + "dev": true, + "license": "MIT", + "dependencies": { + "format": "^0.2.0" + }, + "funding": { + "type": "github", + "url": "https://github.com/sponsors/wooorm" + } + }, "node_modules/fdir": { "version": "6.5.0", "resolved": "https://registry.npmjs.org/fdir/-/fdir-6.5.0.tgz", @@ -4972,6 +4966,15 @@ "url": "https://github.com/sponsors/isaacs" } }, + "node_modules/format": { + "version": "0.2.2", + "resolved": "https://registry.npmjs.org/format/-/format-0.2.2.tgz", + "integrity": "sha512-wzsgA6WOq+09wrU1tsJ09udeR/YZRaeArL9e1wPbFg3GG2yDnC2ldKpxs4xunpFF9DgqCqOIra3bc1HWrJ37Ww==", + "dev": true, + "engines": { + "node": ">=0.4.x" + } + }, "node_modules/fs-extra": { "version": "11.3.4", "resolved": "https://registry.npmjs.org/fs-extra/-/fs-extra-11.3.4.tgz", @@ -6238,6 +6241,38 @@ "url": "https://opencollective.com/unified" } }, + "node_modules/mdast-util-frontmatter": { + "version": "2.0.1", + "resolved": "https://registry.npmjs.org/mdast-util-frontmatter/-/mdast-util-frontmatter-2.0.1.tgz", + "integrity": "sha512-LRqI9+wdgC25P0URIJY9vwocIzCcksduHQ9OF2joxQoyTNVduwLAFUzjoopuRJbJAReaKrNQKAZKL3uCMugWJA==", + "dev": true, + "license": "MIT", + "dependencies": { + "@types/mdast": "^4.0.0", + "devlop": "^1.0.0", + "escape-string-regexp": "^5.0.0", + "mdast-util-from-markdown": "^2.0.0", + "mdast-util-to-markdown": "^2.0.0", + "micromark-extension-frontmatter": "^2.0.0" + }, + "funding": { + "type": "opencollective", + "url": "https://opencollective.com/unified" + } + }, + "node_modules/mdast-util-frontmatter/node_modules/escape-string-regexp": { + "version": "5.0.0", + "resolved": "https://registry.npmjs.org/escape-string-regexp/-/escape-string-regexp-5.0.0.tgz", + "integrity": "sha512-/veY75JbMK4j1yjvuUxuVsiS/hr/4iHs9FTT6cgTexxdE0Ly/glccBAkloH/DofkjRbZU3bnoj38mOmhkZ0lHw==", + "dev": true, + "license": "MIT", + "engines": { + "node": ">=12" + }, + "funding": { + "url": "https://github.com/sponsors/sindresorhus" + } + }, "node_modules/mdast-util-gfm": { "version": "3.1.0", "resolved": "https://registry.npmjs.org/mdast-util-gfm/-/mdast-util-gfm-3.1.0.tgz", @@ -6604,6 +6639,23 @@ "micromark-util-types": "^2.0.0" } }, + "node_modules/micromark-extension-frontmatter": { + "version": "2.0.0", + "resolved": "https://registry.npmjs.org/micromark-extension-frontmatter/-/micromark-extension-frontmatter-2.0.0.tgz", + "integrity": "sha512-C4AkuM3dA58cgZha7zVnuVxBhDsbttIMiytjgsM2XbHAB2faRVaHRle40558FBN+DJcrLNCoqG5mlrpdU4cRtg==", + "dev": true, + "license": "MIT", + "dependencies": { + "fault": "^2.0.0", + "micromark-util-character": "^2.0.0", + "micromark-util-symbol": "^2.0.0", + "micromark-util-types": "^2.0.0" + }, + "funding": { + "type": "opencollective", + "url": "https://opencollective.com/unified" + } + }, "node_modules/micromark-extension-gfm": { "version": "3.0.0", "resolved": "https://registry.npmjs.org/micromark-extension-gfm/-/micromark-extension-gfm-3.0.0.tgz", @@ -8274,6 +8326,23 @@ "url": "https://opencollective.com/unified" } }, + "node_modules/remark-frontmatter": { + "version": "5.0.0", + "resolved": "https://registry.npmjs.org/remark-frontmatter/-/remark-frontmatter-5.0.0.tgz", + "integrity": "sha512-XTFYvNASMe5iPN0719nPrdItC9aU0ssC4v14mH1BCi1u0n1gAocqcujWUrByftZTbLhRtiKRyjYTSIOcr69UVQ==", + "dev": true, + "license": "MIT", + "dependencies": { + "@types/mdast": "^4.0.0", + "mdast-util-frontmatter": "^2.0.0", + "micromark-extension-frontmatter": "^2.0.0", + "unified": "^11.0.0" + }, + "funding": { + "type": "opencollective", + "url": "https://opencollective.com/unified" + } + }, "node_modules/remark-gfm": { "version": "4.0.1", "resolved": "https://registry.npmjs.org/remark-gfm/-/remark-gfm-4.0.1.tgz", diff --git a/package.json b/package.json index baddce2..f6c42e5 100644 --- a/package.json +++ b/package.json @@ -1,6 +1,5 @@ { "scripts": { - "prebuild": "node scripts/generate-component-config.mjs", "build": "doc-kit generate -t web -t orama-db --config-file doc-kit.config.mjs", "lint": "eslint .", "lint:fix": "eslint --fix .", @@ -10,7 +9,7 @@ }, "devDependencies": { "@eslint/js": "^10.0.1", - "@node-core/doc-kit": "1.2.1", + "@node-core/doc-kit": "1.3.0", "@node-core/remark-lint": "^1.3.0", "eslint": "^10.1.0", "eslint-plugin-mdx": "^3.7.0", @@ -18,6 +17,7 @@ "husky": "^9.1.7", "lint-staged": "^16.4.0", "prettier": "^3.8.1", + "remark-frontmatter": "^5.0.0", "typescript-eslint": "^8.57.2" }, "dependencies": { diff --git a/pages/asynchronous-work/asynchronous-flow-control.md b/pages/asynchronous-work/asynchronous-flow-control.md index fccee7d..6a72777 100644 --- a/pages/asynchronous-work/asynchronous-flow-control.md +++ b/pages/asynchronous-work/asynchronous-flow-control.md @@ -1,6 +1,6 @@ - +--- # Asynchronous flow control diff --git a/pages/asynchronous-work/backpressuring-in-streams.md b/pages/asynchronous-work/backpressuring-in-streams.md index b1d85b4..e9992e4 100644 --- a/pages/asynchronous-work/backpressuring-in-streams.md +++ b/pages/asynchronous-work/backpressuring-in-streams.md @@ -1,6 +1,3 @@ - - # Backpressuring in Streams There is a general problem that occurs during data handling called diff --git a/pages/asynchronous-work/discover-javascript-timers.md b/pages/asynchronous-work/discover-javascript-timers.md index 85f71ed..908c816 100644 --- a/pages/asynchronous-work/discover-javascript-timers.md +++ b/pages/asynchronous-work/discover-javascript-timers.md @@ -1,6 +1,6 @@ - +--- # Discover JavaScript Timers diff --git a/pages/asynchronous-work/discover-promises-in-nodejs.md b/pages/asynchronous-work/discover-promises-in-nodejs.md index 3081547..8af7448 100644 --- a/pages/asynchronous-work/discover-promises-in-nodejs.md +++ b/pages/asynchronous-work/discover-promises-in-nodejs.md @@ -1,6 +1,6 @@ - +--- # Discover Promises in Node.js diff --git a/pages/asynchronous-work/dont-block-the-event-loop.md b/pages/asynchronous-work/dont-block-the-event-loop.md index 9eb4cd3..f6f3d0d 100644 --- a/pages/asynchronous-work/dont-block-the-event-loop.md +++ b/pages/asynchronous-work/dont-block-the-event-loop.md @@ -1,6 +1,3 @@ - - # Don't Block the Event Loop (or the Worker Pool) ## Should you read this guide? diff --git a/pages/asynchronous-work/event-loop-timers-and-nexttick.md b/pages/asynchronous-work/event-loop-timers-and-nexttick.md index 0780d08..e5453e0 100644 --- a/pages/asynchronous-work/event-loop-timers-and-nexttick.md +++ b/pages/asynchronous-work/event-loop-timers-and-nexttick.md @@ -1,6 +1,3 @@ - - # The Node.js Event Loop ## What is the Event Loop? diff --git a/pages/asynchronous-work/how-to-use-streams.md b/pages/asynchronous-work/how-to-use-streams.md index 7039487..e306ac6 100644 --- a/pages/asynchronous-work/how-to-use-streams.md +++ b/pages/asynchronous-work/how-to-use-streams.md @@ -1,6 +1,6 @@ - +--- # How To Use Streams diff --git a/pages/asynchronous-work/javascript-asynchronous-programming-and-callbacks.md b/pages/asynchronous-work/javascript-asynchronous-programming-and-callbacks.md index 9312269..9c07b0a 100644 --- a/pages/asynchronous-work/javascript-asynchronous-programming-and-callbacks.md +++ b/pages/asynchronous-work/javascript-asynchronous-programming-and-callbacks.md @@ -1,6 +1,6 @@ - +--- # JavaScript Asynchronous Programming and Callbacks diff --git a/pages/asynchronous-work/overview-of-blocking-vs-non-blocking.md b/pages/asynchronous-work/overview-of-blocking-vs-non-blocking.md index c93a965..adcfaee 100644 --- a/pages/asynchronous-work/overview-of-blocking-vs-non-blocking.md +++ b/pages/asynchronous-work/overview-of-blocking-vs-non-blocking.md @@ -1,6 +1,6 @@ - +--- # Overview of Blocking vs Non-Blocking diff --git a/pages/asynchronous-work/the-nodejs-event-emitter.md b/pages/asynchronous-work/the-nodejs-event-emitter.md index 4110626..d7c7e6e 100644 --- a/pages/asynchronous-work/the-nodejs-event-emitter.md +++ b/pages/asynchronous-work/the-nodejs-event-emitter.md @@ -1,6 +1,6 @@ - +--- # The Node.js Event emitter diff --git a/pages/asynchronous-work/understanding-processnexttick.md b/pages/asynchronous-work/understanding-processnexttick.md index a64a8b3..5c91816 100644 --- a/pages/asynchronous-work/understanding-processnexttick.md +++ b/pages/asynchronous-work/understanding-processnexttick.md @@ -1,6 +1,6 @@ - +--- # Understanding process.nextTick() diff --git a/pages/asynchronous-work/understanding-setimmediate.md b/pages/asynchronous-work/understanding-setimmediate.md index 3893337..a3368aa 100644 --- a/pages/asynchronous-work/understanding-setimmediate.md +++ b/pages/asynchronous-work/understanding-setimmediate.md @@ -1,6 +1,6 @@ - +--- # Understanding setImmediate() diff --git a/pages/command-line/accept-input-from-the-command-line-in-nodejs.md b/pages/command-line/accept-input-from-the-command-line-in-nodejs.md index 516ff20..7e523b0 100644 --- a/pages/command-line/accept-input-from-the-command-line-in-nodejs.md +++ b/pages/command-line/accept-input-from-the-command-line-in-nodejs.md @@ -1,6 +1,6 @@ - +--- # Accept input from the command line in Node.js diff --git a/pages/command-line/how-to-read-environment-variables-from-nodejs.md b/pages/command-line/how-to-read-environment-variables-from-nodejs.md index 46c4a9f..7ad0eb0 100644 --- a/pages/command-line/how-to-read-environment-variables-from-nodejs.md +++ b/pages/command-line/how-to-read-environment-variables-from-nodejs.md @@ -1,6 +1,6 @@ - +--- # How to read environment variables from Node.js diff --git a/pages/command-line/how-to-use-the-nodejs-repl.md b/pages/command-line/how-to-use-the-nodejs-repl.md index 5ccc91a..7b4a19c 100644 --- a/pages/command-line/how-to-use-the-nodejs-repl.md +++ b/pages/command-line/how-to-use-the-nodejs-repl.md @@ -1,6 +1,6 @@ - +--- # How to use the Node.js REPL diff --git a/pages/command-line/output-to-the-command-line-using-nodejs.md b/pages/command-line/output-to-the-command-line-using-nodejs.md index 34dcc29..3017c2e 100644 --- a/pages/command-line/output-to-the-command-line-using-nodejs.md +++ b/pages/command-line/output-to-the-command-line-using-nodejs.md @@ -1,6 +1,6 @@ - +--- # Output to the command line using Node.js diff --git a/pages/command-line/run-nodejs-scripts-from-the-command-line.md b/pages/command-line/run-nodejs-scripts-from-the-command-line.md index 1e13e2d..b4260dc 100644 --- a/pages/command-line/run-nodejs-scripts-from-the-command-line.md +++ b/pages/command-line/run-nodejs-scripts-from-the-command-line.md @@ -1,6 +1,6 @@ - +--- # Run Node.js scripts from the command line diff --git a/pages/diagnostics/debugging.md b/pages/diagnostics/debugging.md index b9fdcfa..c581152 100644 --- a/pages/diagnostics/debugging.md +++ b/pages/diagnostics/debugging.md @@ -1,6 +1,3 @@ - - # Debugging Node.js This guide will help you get started debugging your Node.js apps and scripts. diff --git a/pages/diagnostics/flame-graphs.md b/pages/diagnostics/flame-graphs.md index 493c618..73f9701 100644 --- a/pages/diagnostics/flame-graphs.md +++ b/pages/diagnostics/flame-graphs.md @@ -1,6 +1,3 @@ - - # Flame Graphs ## What's a flame graph useful for? diff --git a/pages/diagnostics/live-debugging/index.md b/pages/diagnostics/live-debugging/index.md index 0115cd2..03b9311 100644 --- a/pages/diagnostics/live-debugging/index.md +++ b/pages/diagnostics/live-debugging/index.md @@ -1,6 +1,3 @@ - - # Live Debugging In this document you can learn about how to live debug a Node.js process. diff --git a/pages/diagnostics/live-debugging/using-inspector.md b/pages/diagnostics/live-debugging/using-inspector.md index 9338437..e0365d5 100644 --- a/pages/diagnostics/live-debugging/using-inspector.md +++ b/pages/diagnostics/live-debugging/using-inspector.md @@ -1,6 +1,3 @@ - - # Using Inspector In a local environment, we usually speak about live debugging where we attach a diff --git a/pages/diagnostics/memory/index.md b/pages/diagnostics/memory/index.md index 255d6d7..024dc99 100644 --- a/pages/diagnostics/memory/index.md +++ b/pages/diagnostics/memory/index.md @@ -1,6 +1,3 @@ - - # Memory In this document you can learn about how to debug memory related issues. diff --git a/pages/diagnostics/memory/understanding-and-tuning-memory.md b/pages/diagnostics/memory/understanding-and-tuning-memory.md index 24044e5..fb0f128 100644 --- a/pages/diagnostics/memory/understanding-and-tuning-memory.md +++ b/pages/diagnostics/memory/understanding-and-tuning-memory.md @@ -1,6 +1,6 @@ - +--- # Understanding and Tuning Memory diff --git a/pages/diagnostics/memory/using-gc-traces.md b/pages/diagnostics/memory/using-gc-traces.md index f1ef900..19b8c5d 100644 --- a/pages/diagnostics/memory/using-gc-traces.md +++ b/pages/diagnostics/memory/using-gc-traces.md @@ -1,6 +1,3 @@ - - # Tracing garbage collection This guide will go through the fundamentals of garbage collection traces. diff --git a/pages/diagnostics/memory/using-heap-profiler.md b/pages/diagnostics/memory/using-heap-profiler.md index f868a42..7486353 100644 --- a/pages/diagnostics/memory/using-heap-profiler.md +++ b/pages/diagnostics/memory/using-heap-profiler.md @@ -1,6 +1,3 @@ - - # Using Heap Profiler The heap profiler acts on top of V8 to capture allocations over time. In this diff --git a/pages/diagnostics/memory/using-heap-snapshot.md b/pages/diagnostics/memory/using-heap-snapshot.md index 2059987..ecccb66 100644 --- a/pages/diagnostics/memory/using-heap-snapshot.md +++ b/pages/diagnostics/memory/using-heap-snapshot.md @@ -1,6 +1,3 @@ - - # Using Heap Snapshot You can take a Heap Snapshot from your running application and load it into diff --git a/pages/diagnostics/poor-performance/index.md b/pages/diagnostics/poor-performance/index.md index 56e5459..c4511c4 100644 --- a/pages/diagnostics/poor-performance/index.md +++ b/pages/diagnostics/poor-performance/index.md @@ -1,6 +1,3 @@ - - # Poor Performance In this document you can learn about how to profile a Node.js process. diff --git a/pages/diagnostics/poor-performance/using-linux-perf.md b/pages/diagnostics/poor-performance/using-linux-perf.md index 44b4a0c..1ae76de 100644 --- a/pages/diagnostics/poor-performance/using-linux-perf.md +++ b/pages/diagnostics/poor-performance/using-linux-perf.md @@ -1,6 +1,3 @@ - - # Using Linux Perf [Linux Perf](https://perf.wiki.kernel.org/index.php/Main_Page) provides low level CPU profiling with JavaScript, diff --git a/pages/diagnostics/profiling.md b/pages/diagnostics/profiling.md index 1edd330..d864dfa 100644 --- a/pages/diagnostics/profiling.md +++ b/pages/diagnostics/profiling.md @@ -1,6 +1,3 @@ - - # Profiling Node.js Applications Profiling a Node.js application involves measuring its performance by analyzing diff --git a/pages/diagnostics/user-journey.md b/pages/diagnostics/user-journey.md index 7f1f856..13d429a 100644 --- a/pages/diagnostics/user-journey.md +++ b/pages/diagnostics/user-journey.md @@ -1,6 +1,3 @@ - - # User Journey These diagnostics guides were created by the [Diagnostics Working Group][] diff --git a/pages/file-system/nodejs-file-paths.md b/pages/file-system/nodejs-file-paths.md index 32a6d2e..e756420 100644 --- a/pages/file-system/nodejs-file-paths.md +++ b/pages/file-system/nodejs-file-paths.md @@ -1,6 +1,6 @@ - +--- # Node.js File Paths diff --git a/pages/file-system/nodejs-file-stats.md b/pages/file-system/nodejs-file-stats.md index b3024bf..9f6b6b7 100644 --- a/pages/file-system/nodejs-file-stats.md +++ b/pages/file-system/nodejs-file-stats.md @@ -1,6 +1,6 @@ - +--- # Node.js file stats diff --git a/pages/file-system/reading-files-with-nodejs.md b/pages/file-system/reading-files-with-nodejs.md index 6fdc7cc..1de56db 100644 --- a/pages/file-system/reading-files-with-nodejs.md +++ b/pages/file-system/reading-files-with-nodejs.md @@ -1,6 +1,6 @@ - +--- # Reading files with Node.js diff --git a/pages/file-system/working-with-different-filesystems.md b/pages/file-system/working-with-different-filesystems.md index 6f82a8e..7b24eb6 100644 --- a/pages/file-system/working-with-different-filesystems.md +++ b/pages/file-system/working-with-different-filesystems.md @@ -1,6 +1,3 @@ - - # How to Work with Different Filesystems Node.js exposes many features of the filesystem. But not all filesystems are alike. diff --git a/pages/file-system/working-with-file-descriptors-in-nodejs.md b/pages/file-system/working-with-file-descriptors-in-nodejs.md index 963df44..d23fccc 100644 --- a/pages/file-system/working-with-file-descriptors-in-nodejs.md +++ b/pages/file-system/working-with-file-descriptors-in-nodejs.md @@ -1,6 +1,6 @@ - +--- # Working with file descriptors in Node.js diff --git a/pages/file-system/working-with-folders-in-nodejs.md b/pages/file-system/working-with-folders-in-nodejs.md index 7335fce..22dea53 100644 --- a/pages/file-system/working-with-folders-in-nodejs.md +++ b/pages/file-system/working-with-folders-in-nodejs.md @@ -1,6 +1,6 @@ - +--- # Working with folders in Node.js diff --git a/pages/file-system/writing-files-with-nodejs.md b/pages/file-system/writing-files-with-nodejs.md index dc27a13..0a8a199 100644 --- a/pages/file-system/writing-files-with-nodejs.md +++ b/pages/file-system/writing-files-with-nodejs.md @@ -1,6 +1,6 @@ - +--- # Writing files with Node.js diff --git a/pages/getting-started/differences-between-nodejs-and-the-browser.md b/pages/getting-started/differences-between-nodejs-and-the-browser.md index 96c6957..28023d3 100644 --- a/pages/getting-started/differences-between-nodejs-and-the-browser.md +++ b/pages/getting-started/differences-between-nodejs-and-the-browser.md @@ -1,6 +1,6 @@ - +--- # Differences between Node.js and the Browser diff --git a/pages/getting-started/ecmascript-2015-es6-and-beyond.md b/pages/getting-started/ecmascript-2015-es6-and-beyond.md index a5d37a6..ec850e9 100644 --- a/pages/getting-started/ecmascript-2015-es6-and-beyond.md +++ b/pages/getting-started/ecmascript-2015-es6-and-beyond.md @@ -1,6 +1,6 @@ - +--- # ECMAScript 2015 (ES6) and beyond diff --git a/pages/getting-started/how-much-javascript-do-you-need-to-know-to-use-nodejs.md b/pages/getting-started/how-much-javascript-do-you-need-to-know-to-use-nodejs.md index d7fc882..104759d 100644 --- a/pages/getting-started/how-much-javascript-do-you-need-to-know-to-use-nodejs.md +++ b/pages/getting-started/how-much-javascript-do-you-need-to-know-to-use-nodejs.md @@ -1,6 +1,6 @@ - +--- # How much JavaScript do you need to know to use Node.js? diff --git a/pages/getting-started/introduction-to-nodejs.md b/pages/getting-started/introduction-to-nodejs.md index 343df76..2c591ed 100644 --- a/pages/getting-started/introduction-to-nodejs.md +++ b/pages/getting-started/introduction-to-nodejs.md @@ -1,6 +1,6 @@ - +--- # Introduction to Node.js diff --git a/pages/getting-started/nodejs-the-difference-between-development-and-production.md b/pages/getting-started/nodejs-the-difference-between-development-and-production.md index 6d98e2d..7439fdd 100644 --- a/pages/getting-started/nodejs-the-difference-between-development-and-production.md +++ b/pages/getting-started/nodejs-the-difference-between-development-and-production.md @@ -1,6 +1,6 @@ - +--- # Node.js, the difference between development and production diff --git a/pages/getting-started/nodejs-with-webassembly.md b/pages/getting-started/nodejs-with-webassembly.md index ddeafe1..c92dd12 100644 --- a/pages/getting-started/nodejs-with-webassembly.md +++ b/pages/getting-started/nodejs-with-webassembly.md @@ -1,6 +1,6 @@ - +--- # Node.js with WebAssembly diff --git a/pages/getting-started/the-v8-javascript-engine.md b/pages/getting-started/the-v8-javascript-engine.md index 1263b89..76f7169 100644 --- a/pages/getting-started/the-v8-javascript-engine.md +++ b/pages/getting-started/the-v8-javascript-engine.md @@ -1,6 +1,6 @@ - +--- # The V8 JavaScript Engine diff --git a/pages/getting-started/userland-migrations.md b/pages/getting-started/userland-migrations.md index 2844c1e..4bd8e08 100644 --- a/pages/getting-started/userland-migrations.md +++ b/pages/getting-started/userland-migrations.md @@ -1,6 +1,6 @@ - +--- # Userland Migrations diff --git a/pages/http/anatomy-of-an-http-transaction.md b/pages/http/anatomy-of-an-http-transaction.md index 68864fa..54cd303 100644 --- a/pages/http/anatomy-of-an-http-transaction.md +++ b/pages/http/anatomy-of-an-http-transaction.md @@ -1,6 +1,3 @@ - - # Anatomy of an HTTP Transaction The purpose of this guide is to impart a solid understanding of the process of diff --git a/pages/http/enterprise-network-configuration.md b/pages/http/enterprise-network-configuration.md index a532511..dd84715 100644 --- a/pages/http/enterprise-network-configuration.md +++ b/pages/http/enterprise-network-configuration.md @@ -1,6 +1,6 @@ - +--- # Enterprise Network Configuration diff --git a/pages/http/fetch.md b/pages/http/fetch.md index 71bffd5..91df6fe 100644 --- a/pages/http/fetch.md +++ b/pages/http/fetch.md @@ -1,6 +1,6 @@ - +--- # Using the Fetch API with Undici in Node.js diff --git a/pages/http/websocket.md b/pages/http/websocket.md index 951416f..5d9ce49 100644 --- a/pages/http/websocket.md +++ b/pages/http/websocket.md @@ -1,6 +1,6 @@ - +--- # Native WebSocket Client in Node.js diff --git a/pages/index.md b/pages/index.md index b90fdc2..667767a 100644 --- a/pages/index.md +++ b/pages/index.md @@ -1,6 +1,6 @@ - +--- # Learn Node.js diff --git a/pages/package-management/abi-stability.md b/pages/package-management/abi-stability.md index 8ef949f..f757949 100644 --- a/pages/package-management/abi-stability.md +++ b/pages/package-management/abi-stability.md @@ -1,6 +1,3 @@ - - # ABI Stability ## Introduction diff --git a/pages/package-management/an-introduction-to-the-npm-package-manager.md b/pages/package-management/an-introduction-to-the-npm-package-manager.md index aa61cdc..f043ecb 100644 --- a/pages/package-management/an-introduction-to-the-npm-package-manager.md +++ b/pages/package-management/an-introduction-to-the-npm-package-manager.md @@ -1,6 +1,6 @@ - +--- # An introduction to the npm package manager diff --git a/pages/package-management/publishing-a-package.md b/pages/package-management/publishing-a-package.md index ab92e1a..2ed0c8f 100644 --- a/pages/package-management/publishing-a-package.md +++ b/pages/package-management/publishing-a-package.md @@ -1,6 +1,6 @@ - +--- # Publishing a package diff --git a/pages/package-management/publishing-node-api-modules.md b/pages/package-management/publishing-node-api-modules.md index 50c048f..040e0be 100644 --- a/pages/package-management/publishing-node-api-modules.md +++ b/pages/package-management/publishing-node-api-modules.md @@ -1,6 +1,3 @@ - - # How to publish a Node-API version of a package alongside a non-Node-API version The following steps are illustrated using the package `iotivity-node`: diff --git a/pages/security/security-best-practices.md b/pages/security/security-best-practices.md index 47d301c..a4257e5 100644 --- a/pages/security/security-best-practices.md +++ b/pages/security/security-best-practices.md @@ -1,6 +1,6 @@ - +--- # Security Best Practices diff --git a/pages/testing/collecting-code-coverage.md b/pages/testing/collecting-code-coverage.md index e28d143..ecc93d4 100644 --- a/pages/testing/collecting-code-coverage.md +++ b/pages/testing/collecting-code-coverage.md @@ -1,6 +1,6 @@ - +--- # Collecting code coverage in Node.js diff --git a/pages/testing/introduction.md b/pages/testing/introduction.md index b809a6d..f680240 100644 --- a/pages/testing/introduction.md +++ b/pages/testing/introduction.md @@ -1,6 +1,6 @@ - +--- # Discovering Node.js's test runner diff --git a/pages/testing/mocking.md b/pages/testing/mocking.md index fa60906..d6ba0a0 100644 --- a/pages/testing/mocking.md +++ b/pages/testing/mocking.md @@ -1,6 +1,6 @@ - +--- # Mocking in tests diff --git a/pages/testing/using-test-runner.md b/pages/testing/using-test-runner.md index dc66c40..4ceb674 100644 --- a/pages/testing/using-test-runner.md +++ b/pages/testing/using-test-runner.md @@ -1,6 +1,6 @@ - +--- # Using Node.js's test runner diff --git a/pages/typescript/introduction.md b/pages/typescript/introduction.md index f18e8ab..536a334 100644 --- a/pages/typescript/introduction.md +++ b/pages/typescript/introduction.md @@ -1,6 +1,6 @@ - +--- # Introduction to TypeScript diff --git a/pages/typescript/publishing-a-ts-package.md b/pages/typescript/publishing-a-ts-package.md index 539f305..fe6efad 100644 --- a/pages/typescript/publishing-a-ts-package.md +++ b/pages/typescript/publishing-a-ts-package.md @@ -1,6 +1,6 @@ - +--- # Publishing a TypeScript package diff --git a/pages/typescript/run-natively.md b/pages/typescript/run-natively.md index eed0fed..a5df048 100644 --- a/pages/typescript/run-natively.md +++ b/pages/typescript/run-natively.md @@ -1,6 +1,6 @@ - +--- # Running TypeScript Natively diff --git a/pages/typescript/run.md b/pages/typescript/run.md index 586d58a..1fd115c 100644 --- a/pages/typescript/run.md +++ b/pages/typescript/run.md @@ -1,6 +1,6 @@ - +--- # Running TypeScript with a runner diff --git a/pages/typescript/transpile.md b/pages/typescript/transpile.md index bcf36e0..2e3dc20 100644 --- a/pages/typescript/transpile.md +++ b/pages/typescript/transpile.md @@ -1,6 +1,6 @@ - +--- # Running TypeScript code using transpilation diff --git a/scripts/constants.mjs b/scripts/constants.mjs deleted file mode 100644 index 12950c5..0000000 --- a/scripts/constants.mjs +++ /dev/null @@ -1,40 +0,0 @@ -import { join } from 'node:path'; - -// Input -export const PAGES_DIR = join(import.meta.dirname, '..', 'pages'); - -// Output -export const OUTPUT_FILE = join( - import.meta.dirname, - '..', - 'components', - 'config.json' -); - -// Index -export const INDEX_FILE = join(PAGES_DIR, 'index.md'); - -// Site navigation -export const NAV_URL = - 'https://raw.githubusercontent.com/nodejs/nodejs.org/main/apps/site/navigation.json'; - -// Site translations -export const I18N_URL = - 'https://raw.githubusercontent.com/nodejs/nodejs.org/main/packages/i18n/src/locales/en.json'; - -// Authors -// TODO(@avivkeller): What if we fetched this data from GitHub directly? -export const AUTHORS_URL = - 'https://raw.githubusercontent.com/nodejs/nodejs.org/refs/heads/main/apps/site/authors.json'; - -// Matches the first H1 heading in a markdown string (e.g. `# Title`) -export const HEADING_RE = /^#\s+(.+)$/m; - -// Matches group slugs from index.md links (e.g. `](/guides/`) -export const GROUP_SLUG_RE = /\]\(\/([\w-]+)\//g; - -// Matches an HTML comment YAML block (e.g. ``) -export const YAML_BLOCK_RE = //; - -// Matches the `authors:` line inside a YAML block -export const AUTHORS_LINE_RE = /^authors:\s*(.+)$/m; diff --git a/scripts/generate-component-config.mjs b/scripts/generate-component-config.mjs deleted file mode 100644 index 2ef13e2..0000000 --- a/scripts/generate-component-config.mjs +++ /dev/null @@ -1,124 +0,0 @@ -import { readFile, writeFile, glob } from 'node:fs/promises'; -import { join } from 'node:path'; -import { OUTPUT_FILE, INDEX_FILE, PAGES_DIR } from './constants.mjs'; -import config from '../doc-kit.config.mjs'; -import { populate } from '@node-core/doc-kit/src/utils/configuration/templates.mjs'; -import { - extractGroupOrder, - fetchAuthorsMap, - fetchTopNav, - parsePage, - resolveAuthor, - slugToTitle, -} from './utils.mjs'; - -/** - * @typedef {Object} AuthorEntry - * @property {string} id GitHub username used as a unique key. - * @property {string} [name] Display name (falls back to `id`). - * @property {string} [website] Personal URL (falls back to GitHub profile). - */ - -/** - * @typedef {Object} ResolvedAuthor - * @property {string} image GitHub avatar URL. - * @property {string} name Display name. - * @property {string} nickname GitHub username. - * @property {string} fallback Uppercase initials used as an avatar fallback. - * @property {string} url Link to the author's website or GitHub profile. - */ - -/** - * @typedef {Object} NavItem - * @property {string} link Destination URL. - * @property {string} text Visible label. - * @property {string} [target] Optional link target (e.g. `"_blank"`). - */ - -/** - * @typedef {Object} SideNavGroup - * @property {string} groupName Human-readable group heading. - * @property {{ label: string, link: string }[]} items Pages in this group. - */ - -/** - * @typedef {Object} ParsedPage - * @property {string} group Top-level directory slug (first path segment). - * @property {string} pathname URL pathname derived from the file path. - * @property {string} label Page title extracted from the first H1. - * @property {Array} authorIds GitHub usernames listed in the YAML front-matter. - */ - -/** - * @typedef {Object} BuildOutput - * @property {SideNavGroup[]} sideNav Grouped sidebar navigation. - * @property {Record} authors Authors keyed by edit URL. - */ - -/** - * Builds the edit-URL key used to index into the authors map. - * @param {string} pathname URL pathname of the page. - * @returns {string} Fully-qualified edit URL. - */ -const toEditUrl = pathname => - populate(config['jsx-ast'].editURL, { path: pathname }); - -/** - * Reads every markdown page under {@link PAGES_DIR} and produces the sidebar - * navigation groups and a per-page authors mapping. - * @param {Map} authorsById Lookup map of known authors. - * @returns {Promise} - */ -const buildPages = async authorsById => { - const [files, indexContent] = await Promise.all([ - Array.fromAsync(glob('**/*.md', { cwd: PAGES_DIR, exclude: ['index.md'] })), - readFile(INDEX_FILE, 'utf-8'), - ]); - - const groupOrder = extractGroupOrder(indexContent); - - const pages = await Promise.all( - files.map(async file => { - const content = await readFile(join(PAGES_DIR, file), 'utf-8'); - return parsePage(file, content); - }) - ); - const groups = Map.groupBy(pages, p => p.group); - - // Sort entries by their position in index.md (unknown groups go to the end) - const sortedEntries = [...groups.entries()].sort( - (a, b) => - (groupOrder.indexOf(a[0]) >>> 0) - (groupOrder.indexOf(b[0]) >>> 0) - ); - - const sideNav = sortedEntries.map(([key, items]) => ({ - groupName: slugToTitle(key), - items: items.map(({ label, pathname }) => ({ - label, - link: `/learn${pathname}.html`, - })), - })); - - const authors = Object.fromEntries( - pages - .filter(({ authorIds }) => authorIds.length > 0) - .map(({ pathname, authorIds }) => [ - toEditUrl(pathname), - authorIds.map(id => resolveAuthor(id, authorsById)), - ]) - ); - - return { sideNav, authors }; -}; - -const [authorsById, topNav] = await Promise.all([ - fetchAuthorsMap(), - fetchTopNav(), -]); - -const { sideNav, authors } = await buildPages(authorsById); - -await writeFile( - OUTPUT_FILE, - JSON.stringify({ topNav, sideNav, authors }, null, 2) -); diff --git a/scripts/utils.mjs b/scripts/utils.mjs deleted file mode 100644 index fe0afe6..0000000 --- a/scripts/utils.mjs +++ /dev/null @@ -1,144 +0,0 @@ -import { sep } from 'node:path'; -import { - AUTHORS_LINE_RE, - AUTHORS_URL, - GROUP_SLUG_RE, - HEADING_RE, - I18N_URL, - NAV_URL, - YAML_BLOCK_RE, -} from './constants.mjs'; - -/** - * Extracts the first H1 heading from markdown content. - * @param {string} content Raw markdown string. - * @returns {string} The heading text, or an empty string if none is found. - */ -export const extractTitle = content => - content.match(HEADING_RE)?.[1]?.trim() ?? ''; - -/** - * Extracts the ordered list of group slugs from index.md links. - * @param {string} content Raw markdown of the index file. - * @returns {Array} Ordered, deduplicated group slugs. - */ -export const extractGroupOrder = content => [ - ...new Set([...content.matchAll(GROUP_SLUG_RE)].map(match => match[1])), -]; - -/** - * Extracts author IDs from a `