diff --git a/.changeset/configurable-navigation.md b/.changeset/configurable-navigation.md index cecf529c..869cdc5e 100644 --- a/.changeset/configurable-navigation.md +++ b/.changeset/configurable-navigation.md @@ -1,5 +1,5 @@ --- -'@node-core/doc-kit': patch +'@nodejs/doc-kit': patch --- Add `web.navigation`, which supplies the sidebar groups (`navigation.sidebar`) diff --git a/.changeset/curvy-items-smile.md b/.changeset/curvy-items-smile.md index 69111d7f..7b9492b4 100644 --- a/.changeset/curvy-items-smile.md +++ b/.changeset/curvy-items-smile.md @@ -1,5 +1,5 @@ --- -'@node-core/doc-kit': minor +'@nodejs/doc-kit': minor --- Discover and load configuration files with `cosmiconfig`. diff --git a/.changeset/did-you-know-that-the-world-is-round.md b/.changeset/did-you-know-that-the-world-is-round.md index 98ba0892..b890a4ab 100644 --- a/.changeset/did-you-know-that-the-world-is-round.md +++ b/.changeset/did-you-know-that-the-world-is-round.md @@ -1,5 +1,5 @@ --- -'@node-core/doc-kit': patch +'@nodejs/doc-kit': patch --- Close Orama search when the target link is on the same page diff --git a/.changeset/display-name-type-unions.md b/.changeset/display-name-type-unions.md index 8f91f546..f4b2cdb1 100644 --- a/.changeset/display-name-type-unions.md +++ b/.changeset/display-name-type-unions.md @@ -1,5 +1,5 @@ --- -'@node-core/doc-kit': patch +'@nodejs/doc-kit': patch --- Resolve unions and arrays of display-name types (`{HTTP/2 Headers Object | vm.Module}`, `{HTTP/2 Headers Object[]}`), and stop capturing prose such as `U+007B ({), and U+007D (}).` as a type annotation. diff --git a/.changeset/doc-kit-scope-move.md b/.changeset/doc-kit-scope-move.md new file mode 100644 index 00000000..dd10cf1a --- /dev/null +++ b/.changeset/doc-kit-scope-move.md @@ -0,0 +1,8 @@ +--- +'@nodejs/doc-kit': major +--- + +The doc-kit engine and CLI, previously published as `@node-core/doc-kit`, +are now published as `@nodejs/doc-kit`. The `@node-core/doc-kit` name now +contains only the Node.js-specific generators (`api-links`, `addon-verify`, +and `man-page`). diff --git a/.changeset/fix-relative-parent-path.md b/.changeset/fix-relative-parent-path.md index e3f7ef8e..7745c39b 100644 --- a/.changeset/fix-relative-parent-path.md +++ b/.changeset/fix-relative-parent-path.md @@ -1,5 +1,5 @@ --- -'@node-core/doc-kit': patch +'@nodejs/doc-kit': patch --- Fix `relative()` URL resolution when the target path is a prefix of the current diff --git a/.changeset/legacy-kitten-package.md b/.changeset/legacy-kitten-package.md index 55d49a31..b38a21ca 100644 --- a/.changeset/legacy-kitten-package.md +++ b/.changeset/legacy-kitten-package.md @@ -1,11 +1,11 @@ --- '@nodejs/doc-kit-generator-legacy': major -'@node-core/doc-kit': major +'@nodejs/doc-kit': major --- The legacy-format generators (`legacy-html`, `legacy-html-all`, `legacy-json`, and `legacy-json-all`) now live in the new `@nodejs/doc-kit-generator-legacy` package and are loaded via import specifiers such as `@nodejs/doc-kit-generator-legacy/legacy-html`. The corresponding -`@node-core/doc-kit/*` package exports have been removed. The CLI shorthand +`@nodejs/doc-kit/*` package exports have been removed. The CLI shorthand names are unchanged. diff --git a/.changeset/monorepo-layout.md b/.changeset/monorepo-layout.md index 4341e42d..603f5bc6 100644 --- a/.changeset/monorepo-layout.md +++ b/.changeset/monorepo-layout.md @@ -1,5 +1,5 @@ --- -'@node-core/doc-kit': patch +'@nodejs/doc-kit': patch --- Moved the package into a `packages/core` workspace. diff --git a/.changeset/node-kitten-package.md b/.changeset/node-kitten-package.md new file mode 100644 index 00000000..1fa974c2 --- /dev/null +++ b/.changeset/node-kitten-package.md @@ -0,0 +1,10 @@ +--- +'@node-core/doc-kit': major +'@nodejs/doc-kit': major +--- + +The Node.js-specific generators (`api-links`, `addon-verify`, and +`man-page`) now live in the `@node-core/doc-kit` package and are loaded +via import specifiers such as `@node-core/doc-kit/man-page`. The +corresponding package exports have been removed from the doc-kit engine. +The CLI shorthand names are unchanged. diff --git a/.changeset/opt-out-banners.md b/.changeset/opt-out-banners.md index 652dee33..53f9497a 100644 --- a/.changeset/opt-out-banners.md +++ b/.changeset/opt-out-banners.md @@ -1,5 +1,5 @@ --- -'@node-core/doc-kit': minor +'@nodejs/doc-kit': minor --- Add banner opt-out diff --git a/.changeset/react-kitten-package.md b/.changeset/react-kitten-package.md index cf250c1c..25b93ea9 100644 --- a/.changeset/react-kitten-package.md +++ b/.changeset/react-kitten-package.md @@ -1,12 +1,12 @@ --- '@nodejs/doc-kit-generator-react': minor -'@node-core/doc-kit': major +'@nodejs/doc-kit': major --- The React/JSX-based generators (`html` — previously `web` —, `jsx-ast`, `llms-txt`, `sitemap`, and `orama-db`) now live in the new `@nodejs/doc-kit-generator-react` package and are loaded via import specifiers such as -`@nodejs/doc-kit-generator-react/html`. The corresponding `@node-core/doc-kit/*` +`@nodejs/doc-kit-generator-react/html`. The corresponding `@nodejs/doc-kit/*` package exports have been removed. The `web` generator is renamed to `html`: the CLI shorthand `web` keeps working as a deprecated alias, but the configuration key is now `html` instead of `web`. diff --git a/.changeset/riscv64-warning-spacing.md b/.changeset/riscv64-warning-spacing.md index 58eff4c4..4b60d25e 100644 --- a/.changeset/riscv64-warning-spacing.md +++ b/.changeset/riscv64-warning-spacing.md @@ -1,5 +1,5 @@ --- -'@node-core/doc-kit': patch +'@nodejs/doc-kit': patch --- Fix missing spaces in the riscv64 multithreading warning message, which diff --git a/.changeset/short-deprecation-links.md b/.changeset/short-deprecation-links.md index 8af343c4..7b38dc5c 100644 --- a/.changeset/short-deprecation-links.md +++ b/.changeset/short-deprecation-links.md @@ -1,5 +1,5 @@ --- -'@node-core/doc-kit': patch +'@nodejs/doc-kit': patch --- Use short `DEP` codes for deprecation heading anchors. diff --git a/.changeset/spaced-union-types.md b/.changeset/spaced-union-types.md index 6c831a97..1498134d 100644 --- a/.changeset/spaced-union-types.md +++ b/.changeset/spaced-union-types.md @@ -1,5 +1,5 @@ --- -'@node-core/doc-kit': patch +'@nodejs/doc-kit': patch --- Space union separators in type annotation values (`{string|URL}` is now rendered as `string | URL`). diff --git a/.changeset/specifier-generator-loading.md b/.changeset/specifier-generator-loading.md index 039de74a..e6ee7d58 100644 --- a/.changeset/specifier-generator-loading.md +++ b/.changeset/specifier-generator-loading.md @@ -1,5 +1,5 @@ --- -'@node-core/doc-kit': minor +'@nodejs/doc-kit': minor --- Generators are now loaded dynamically by import specifier instead of a static diff --git a/.changeset/swc.md b/.changeset/swc.md index 9b9a2bf2..ec6c6c6e 100644 --- a/.changeset/swc.md +++ b/.changeset/swc.md @@ -1,5 +1,5 @@ --- -'@node-core/doc-kit': patch +'@nodejs/doc-kit': patch --- Switches `oxc-parser` for `@swc/wasm`, since `oxc-parser` does not provide the needed bindings. diff --git a/.changeset/tidy-deprecations-smile.md b/.changeset/tidy-deprecations-smile.md index d9e7c7bb..fa83f542 100644 --- a/.changeset/tidy-deprecations-smile.md +++ b/.changeset/tidy-deprecations-smile.md @@ -1,5 +1,5 @@ --- -'@node-core/doc-kit': patch +'@nodejs/doc-kit': patch --- Preserve deprecation codes in generated table-of-contents labels. diff --git a/.changeset/tidy-donuts-search.md b/.changeset/tidy-donuts-search.md index 9c48fd61..30e045d4 100644 --- a/.changeset/tidy-donuts-search.md +++ b/.changeset/tidy-donuts-search.md @@ -1,5 +1,5 @@ --- -'@node-core/doc-kit': patch +'@nodejs/doc-kit': patch --- Sync the URL hash when following same-page search hits diff --git a/.changeset/vite-web-generator.md b/.changeset/vite-web-generator.md index 49a47ea6..74f4838b 100644 --- a/.changeset/vite-web-generator.md +++ b/.changeset/vite-web-generator.md @@ -1,5 +1,5 @@ --- -'@node-core/doc-kit': minor +'@nodejs/doc-kit': minor --- Make the `web` generator bundler-neutral through a custom adapter contract, diff --git a/.changeset/yes-i-did-know-that-thank-you.md b/.changeset/yes-i-did-know-that-thank-you.md index b03124c5..370e2bef 100644 --- a/.changeset/yes-i-did-know-that-thank-you.md +++ b/.changeset/yes-i-did-know-that-thank-you.md @@ -1,5 +1,5 @@ --- -'@node-core/doc-kit': patch +'@nodejs/doc-kit': patch --- Render markdown `code` snippets in the sidebar diff --git a/.github/workflows/publish.yml b/.github/workflows/publish.yml index 02b92068..74e7ee8a 100644 --- a/.github/workflows/publish.yml +++ b/.github/workflows/publish.yml @@ -56,9 +56,9 @@ jobs: env: SLACK_COLOR: '#43853D' SLACK_ICON: https://github.com/nodejs.png?size=48 - SLACK_TITLE: ':rocket: Package Published: @node-core/doc-kit' + SLACK_TITLE: ':rocket: doc-kit Packages Published' SLACK_MESSAGE: | - :package: *Package*: `@node-core/doc-kit` () + :package: *Packages*: `nodejs/doc-kit` workspace () :bust_in_silhouette: *Published by*: ${{ github.triggering_actor }} :octocat: *Commit*: SLACK_USERNAME: nodejs-bot diff --git a/.gitignore b/.gitignore index ef3c932b..35a39e94 100644 --- a/.gitignore +++ b/.gitignore @@ -18,7 +18,7 @@ junit.xml isolate-* # Node's Source Folder -node +/node # Playwright playwright-report/ diff --git a/.prettierignore b/.prettierignore index 6e8a14b1..34ea39e2 100644 --- a/.prettierignore +++ b/.prettierignore @@ -1,7 +1,7 @@ npm-shrinkwrap.json # Tests files -packages/core/src/generators/api-links/__tests__/fixtures/ +packages/node/src/api-links/__tests__/fixtures/ *.snapshot # Templates diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index 3b806375..faaf19da 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -1,6 +1,6 @@ -# `@node-core/doc-kit` Contributing Guide +# `@nodejs/doc-kit` Contributing Guide -Thank you for your interest in contributing to the `@node-core/doc-kit` project! We welcome contributions from everyone, and we appreciate your help in making this project better. +Thank you for your interest in contributing to the `@nodejs/doc-kit` project! We welcome contributions from everyone, and we appreciate your help in making this project better. ## Table of Contents @@ -29,7 +29,7 @@ Thank you for your interest in contributing to the `@node-core/doc-kit` project! ## Getting Started -The steps below will give you a general idea of how to prepare your local environment for the `@node-core/doc-kit` project and general steps for getting things done and landing your contribution. +The steps below will give you a general idea of how to prepare your local environment for the `@nodejs/doc-kit` project and general steps for getting things done and landing your contribution. ### Prerequisites @@ -77,7 +77,10 @@ This repository is an npm workspaces monorepo. The root package is private and holds the shared tooling (linting, formatting, tests, changesets); every published package lives under `packages/`: -- `packages/core`: [`@node-core/doc-kit`](packages/core) +- `packages/core`: [`@nodejs/doc-kit`](packages/core) — the doc-kit engine and CLI +- `packages/legacy`: [`@nodejs/doc-kit-generator-legacy`](packages/legacy) — the legacy-format generators +- `packages/node`: [`@node-core/doc-kit`](packages/node) — the Node.js-specific generators +- `packages/react`: [`@nodejs/doc-kit-generator-react`](packages/react) — the React/JSX-based generators Everything else at the root supports the repo rather than shipping to npm: `docs/` (the reference docs), `www/` (the documentation site), `scripts/` (build @@ -357,7 +360,7 @@ version in `package.json`, and writes the corresponding `CHANGELOG.md` entries. To ship a release, a maintainer merges that "Version Packages" PR. The same workflow then: -- publishes `@node-core/doc-kit` to npm (via [npm trusted publishing][] — no token required), +- publishes the workspace packages to npm (via [npm trusted publishing][] — no token required), - creates the matching `v` git tag, and - cuts a GitHub Release from the changelog. diff --git a/README.md b/README.md index 967e4878..b24f5c68 100644 --- a/README.md +++ b/README.md @@ -9,7 +9,7 @@

- @node-core/doc-kit is a tool to generate API documentation of Node.js. See this issue for more information. + @nodejs/doc-kit is a tool to generate API documentation of Node.js. See this issue for more information.

@@ -44,7 +44,7 @@ $ node packages/core/bin/cli.mjs --help ``` ``` -Usage: @node-core/doc-kit [options] [command] +Usage: @nodejs/doc-kit [options] [command] CLI tool to generate the Node.js API documentation @@ -67,7 +67,7 @@ Running `generate` without the required values exits with an error pointing you to the help output. ``` -Usage: @node-core/doc-kit generate [options] +Usage: @nodejs/doc-kit generate [options] Generate API docs diff --git a/docs/comparators.md b/docs/comparators.md index 0046c78a..1cafcd52 100644 --- a/docs/comparators.md +++ b/docs/comparators.md @@ -1,6 +1,6 @@ # Creating Comparators -This guide explains how to create build comparison scripts for `@node-core/doc-kit`. Comparators help identify differences between documentation builds, useful for CI/CD and regression testing. +This guide explains how to create build comparison scripts for `@nodejs/doc-kit`. Comparators help identify differences between documentation builds, useful for CI/CD and regression testing. ## Comparator Concepts diff --git a/docs/configuration.md b/docs/configuration.md index eef68555..214d2857 100644 --- a/docs/configuration.md +++ b/docs/configuration.md @@ -39,7 +39,7 @@ export default { // Targets, alternatively supplied by command line flags. Each entry is // either a built-in shorthand name or an import specifier resolving to a // generator module (e.g. '@my-scope/my-package/my-generator'). - target: ['orama-db', 'web'], + target: ['orama-db', 'html'], global: { version: '20.0.0', minify: true, diff --git a/docs/generators.md b/docs/generators.md index a2048499..a3907501 100644 --- a/docs/generators.md +++ b/docs/generators.md @@ -1,6 +1,6 @@ # Creating Generators -This guide explains how to create new documentation generators for `@node-core/doc-kit`. +This guide explains how to create new documentation generators for `@nodejs/doc-kit`. ## Generator Concepts @@ -88,7 +88,7 @@ export default { // This generator depends on the metadata generator. Dependencies are // declared as import specifiers, so they can live in any package. - dependsOn: '@node-core/doc-kit/metadata', + dependsOn: '@nodejs/doc-kit/metadata', defaultConfiguration: { // If your generator supports a custom configuration, define the defaults here @@ -170,8 +170,8 @@ the import specifier it resolves to: ```javascript export const publicGenerators = { - 'json-simple': '@node-core/doc-kit/json-simple', - 'my-format': '@node-core/doc-kit/my-format', // Add this + 'json-simple': '@nodejs/doc-kit/json-simple', + 'my-format': '@nodejs/doc-kit/my-format', // Add this // ... other generators }; ``` @@ -199,7 +199,7 @@ export default { description: 'Processes data in parallel', - dependsOn: '@node-core/doc-kit/metadata', + dependsOn: '@nodejs/doc-kit/metadata', // Indicates this generator has a processChunk implementation hasParallelProcessor: true, @@ -296,7 +296,7 @@ export default { description: 'Streams results as they are ready', - dependsOn: '@node-core/doc-kit/metadata', + dependsOn: '@nodejs/doc-kit/metadata', hasParallelProcessor: true, @@ -403,7 +403,7 @@ export default { // This generator requires the metadata generator's output. The dependency // is an import specifier, so it may point at any installed package. - dependsOn: '@node-core/doc-kit/metadata', + dependsOn: '@nodejs/doc-kit/metadata', // ... other metadata @@ -434,7 +434,7 @@ export default { // packages/core/src/generators/metadata/index.mjs export default { name: 'metadata', - dependsOn: '@node-core/doc-kit/ast', // Depends on AST + dependsOn: '@nodejs/doc-kit/ast', // Depends on AST // Processes AST output }; @@ -442,7 +442,7 @@ export default { // packages/core/src/generators/html-generator/index.mjs export default { name: 'html-generator', - dependsOn: '@node-core/doc-kit/metadata', // Depends on metadata + dependsOn: '@nodejs/doc-kit/metadata', // Depends on metadata // Processes metadata output }; ``` diff --git a/docs/specification.md b/docs/specification.md index 1012e49f..a1f75ad5 100644 --- a/docs/specification.md +++ b/docs/specification.md @@ -5,7 +5,7 @@ **Authored By**: Aviv Keller () This document specifies the Markdown format consumed by -[`@node-core/doc-kit`][doc-kit]. It defines the structural, syntactic, and +[`@nodejs/doc-kit`][doc-kit]. It defines the structural, syntactic, and semantic rules that documents MUST follow to be correctly parsed. The format is a strict superset of [GitHub Flavored Markdown][gfm] (which itself is a strict superset of [CommonMark][commonmark]), adding conventions for API diff --git a/eslint.config.mjs b/eslint.config.mjs index f8dceaa5..5f890af3 100644 --- a/eslint.config.mjs +++ b/eslint.config.mjs @@ -13,7 +13,7 @@ export default defineConfig([ ignores: [ 'www/out', 'out/', - 'packages/core/src/generators/api-links/__tests__/fixtures/', + 'packages/node/src/api-links/__tests__/fixtures/', ], }, { diff --git a/package-lock.json b/package-lock.json index 71e043ff..c03f0780 100644 --- a/package-lock.json +++ b/package-lock.json @@ -1,11 +1,11 @@ { - "name": "@node-core/doc-kit-monorepo", + "name": "@nodejs/doc-kit-monorepo", "version": "1.4.3", "lockfileVersion": 3, "requires": true, "packages": { "": { - "name": "@node-core/doc-kit-monorepo", + "name": "@nodejs/doc-kit-monorepo", "workspaces": [ "packages/*" ], @@ -1328,7 +1328,7 @@ } }, "node_modules/@node-core/doc-kit": { - "resolved": "packages/core", + "resolved": "packages/node", "link": true }, "node_modules/@node-core/rehype-shiki": { @@ -1387,6 +1387,10 @@ "node": ">=20" } }, + "node_modules/@nodejs/doc-kit": { + "resolved": "packages/core", + "link": true + }, "node_modules/@nodejs/doc-kit-generator-legacy": { "resolved": "packages/legacy", "link": true @@ -11210,8 +11214,8 @@ } }, "packages/core": { - "name": "@node-core/doc-kit", - "version": "1.4.3", + "name": "@nodejs/doc-kit", + "version": "0.0.0", "dependencies": { "@actions/core": "^3.0.0", "@node-core/rehype-shiki": "^1.4.3", @@ -11221,7 +11225,6 @@ "commander": "^15.0.0", "cosmiconfig": "^9.0.2", "dedent": "^1.7.2", - "estree-util-visit": "^2.0.0", "github-slugger": "^2.0.0", "glob-parent": "^6.0.2", "hastscript": "^9.0.1", @@ -11248,10 +11251,14 @@ "doc-kit": "bin/cli.mjs" }, "peerDependencies": { + "@node-core/doc-kit": "^1.4.3", "@nodejs/doc-kit-generator-legacy": "^0.0.0", "@nodejs/doc-kit-generator-react": "^0.0.0" }, "peerDependenciesMeta": { + "@node-core/doc-kit": { + "optional": true + }, "@nodejs/doc-kit-generator-legacy": { "optional": true }, @@ -11264,12 +11271,22 @@ "name": "@nodejs/doc-kit-generator-legacy", "version": "0.0.0", "dependencies": { - "@node-core/doc-kit": "^1.4.3", + "@nodejs/doc-kit": "^0.0.0", "hastscript": "^9.0.1", "unist-builder": "^4.0.0", "unist-util-visit": "^5.1.0" } }, + "packages/node": { + "name": "@node-core/doc-kit", + "version": "1.4.3", + "dependencies": { + "@nodejs/doc-kit": "^0.0.0", + "dedent": "^1.7.2", + "estree-util-visit": "^2.0.0", + "unist-util-visit": "^5.1.0" + } + }, "packages/react": { "name": "@nodejs/doc-kit-generator-react", "version": "0.0.0", @@ -11278,9 +11295,9 @@ "@fontsource-variable/open-sans": "^5.3.0", "@fontsource/ibm-plex-mono": "^5.3.0", "@heroicons/react": "^2.2.0", - "@node-core/doc-kit": "^1.4.3", "@node-core/rehype-shiki": "^1.4.3", "@node-core/ui-components": "^1.7.4", + "@nodejs/doc-kit": "^0.0.0", "@orama/orama": "^3.1.18", "@orama/ui": "^1.5.4", "estree-util-to-js": "^2.0.0", diff --git a/package.json b/package.json index d868527f..5bb1e54f 100644 --- a/package.json +++ b/package.json @@ -1,5 +1,5 @@ { - "name": "@node-core/doc-kit-monorepo", + "name": "@nodejs/doc-kit-monorepo", "private": true, "type": "module", "workspaces": [ diff --git a/packages/core/CHANGELOG.md b/packages/core/CHANGELOG.md index d326689b..92a34618 100644 --- a/packages/core/CHANGELOG.md +++ b/packages/core/CHANGELOG.md @@ -1,4 +1,4 @@ -# @node-core/doc-kit +# @nodejs/doc-kit ## 1.4.3 diff --git a/packages/core/README.md b/packages/core/README.md index 30c43306..3e26f00a 100644 --- a/packages/core/README.md +++ b/packages/core/README.md @@ -1,4 +1,4 @@ -# `@node-core/doc-kit` +# `@nodejs/doc-kit` The core of doc-kit: the CLI and the generators that turn API-shaped Markdown into HTML, JSON, man pages and more. @@ -10,7 +10,7 @@ references. ## Scripts Run these from this directory, or from the repository root with -`npm run