Skip to content

Commit 52f01c8

Browse files
committed
chore: remove the legacy-json and legacy-json-all generators
This removes the rest of the legacy stack, and with it the `@node-core/doc-kit-legacy` package and what only it used in `@doc-kit/core`: `getRemarkRehype` and `rehypeOptions`. The docs site builds its per-page JSON with the `json` generator instead, and the changeset of the `legacy-html` removal no longer bumps the package, which doesn't exist anymore. Node.js's build still targets `legacy-json-all` for `doc/api/*.json` and `all.json` (`tools/doc/web.doc-kit.config.mjs`), so this can only land once Node.js moves to `json` and `json-all`. Assisted-by: Claude Opus 5.5 <[email protected]>
1 parent 8436900 commit 52f01c8

34 files changed

Lines changed: 22 additions & 1163 deletions
Lines changed: 0 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -1,7 +1,6 @@
11
---
22
'@doc-kit/core': major
33
'@doc-kit/cli': major
4-
'@node-core/doc-kit-legacy': major
54
---
65

76
Remove the `legacy-html` and `legacy-html-all` generators, now that Node.js builds its API docs with the redesigned `html` generator. The `@doc-kit/core` exports only they used are removed too: `shiki.config.mjs`, `utils/remark-shiki.mjs`, and the default export of `utils/highlighter.mjs`
Lines changed: 6 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,6 @@
1+
---
2+
'@doc-kit/core': major
3+
'@doc-kit/cli': major
4+
---
5+
6+
Remove the `legacy-json` and `legacy-json-all` generators, and with them the `@node-core/doc-kit-legacy` package, now that Node.js builds the JSON of its API docs with the `json` and `json-all` generators. The `getRemarkRehype` and `rehypeOptions` exports of `@doc-kit/core`'s `utils/remark.mjs`, which only they used, are removed too

‎.github/workflows/generate.yml‎

Lines changed: 0 additions & 4 deletions
Original file line numberDiff line numberDiff line change
@@ -98,10 +98,6 @@ jobs:
9898
input: './node/doc/api/*.md'
9999
compare: object-assertion
100100

101-
- target: legacy-json
102-
input: './node/doc/api/*.md'
103-
compare: object-assertion
104-
105101
- target: web
106102
input: './node/doc/api/*.md'
107103
compare: file-size

‎CONTRIBUTING.md‎

Lines changed: 0 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -80,7 +80,6 @@ published package lives under `packages/`:
8080
- `packages/cli`: [`@doc-kit/cli`](packages/cli) — the doc-kit command-line interface
8181
- `packages/core`: [`@doc-kit/core`](packages/core) — the doc-kit engine
8282
- `packages/node`: [`@node-core/doc-kit`](packages/node) — the Node.js-specific generators
83-
- `packages/node-legacy`: [`@node-core/doc-kit-legacy`](packages/node-legacy) — the Node.js legacy-format generators
8483
- `packages/react`: [`@doc-kit/generator-react`](packages/react) — the React/JSX-based generators
8584

8685
Everything else at the root supports the repo rather than shipping to npm:

‎README.md‎

Lines changed: 4 additions & 16 deletions
Original file line numberDiff line numberDiff line change
@@ -69,10 +69,10 @@ Options:
6969
--config-file <path> Config file
7070
-i, --input <patterns...> Input file patterns (glob)
7171
-t, --target <generator...> Target generator(s): a built-in name (json,
72-
json-all, json-simple, man-page, legacy-json,
73-
legacy-json-all, addon-verify, api-links,
74-
orama-db, llms-txt, sitemap, html, section-pages)
75-
or an import specifier for a custom generator
72+
json-all, json-simple, man-page, addon-verify,
73+
api-links, orama-db, llms-txt, sitemap, html,
74+
section-pages) or an import specifier for a
75+
custom generator
7676
--ignore <patterns...> Ignore file patterns (glob)
7777
-o, --output <directory> The output directory
7878
-p, --threads <number> Number of threads to use (minimum: 1)
@@ -89,18 +89,6 @@ Options:
8989

9090
## Examples
9191

92-
### Legacy
93-
94-
To generate a 1:1 match with the JSON of the [legacy tooling](https://github.com/nodejs/node/tree/main/tools/doc), use the `legacy-json` and `legacy-json-all` generators.
95-
96-
```sh
97-
npx @doc-kit/cli generate \
98-
-t legacy-json \
99-
-i "path/to/node/doc/api/*.md" \
100-
-o out \
101-
--index path/to/node/doc/api/index.md
102-
```
103-
10492
### Redesigned
10593

10694
To generate [our redesigned documentation pages](https://nodejs-api-docs-tooling.vercel.app), use the `html` and `orama-db` (for search) generators. These generators live in the separate [`@doc-kit/generator-react`](packages/react) package, which must be installed alongside this one.

‎docs/configuration.md‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -124,7 +124,7 @@ Everything under the `global` key applies to every generator:
124124
(single-version output).
125125
- `index` {string|URL|Array} Index URL.
126126

127-
A generator's own section (e.g., `html`, `legacy-json`) can override any of
127+
A generator's own section (e.g., `html`, `json`) can override any of
128128
these for that generator alone.
129129

130130
## Execution options

‎docs/contributing/comparators.md‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -40,7 +40,7 @@ scripts/
4040
Comparators can be reused across multiple generators. You specify which comparator to use in the workflow file using the `compare` field. For example:
4141

4242
- `file-size.mjs` can compare output from `html`, `orama-db`, or any generator
43-
- `object-assertion.mjs` can compare JSON output from `legacy-json`, `json-simple`, etc.
43+
- `object-assertion.mjs` can compare JSON output from `json`, `api-links`, etc.
4444
- `my-comparator.mjs` would be a custom comparator for specific needs
4545

4646
The generation workflow also stores timing, CPU, and peak resident memory in

‎docs/generators.md‎

Lines changed: 0 additions & 10 deletions
Original file line numberDiff line numberDiff line change
@@ -26,16 +26,6 @@ npx @doc-kit/cli generate -t html -t orama-db -t sitemap -i "docs/**/*.md" -o ou
2626
| [`json-all`](./generators/json-all.md) | Those documents bundled into a single `all.json`. |
2727
| [`json-simple`](./generators/json-simple.md) | A dump of the parsed metadata entries, for debugging the pipeline. |
2828

29-
### Legacy ([`@node-core/doc-kit-legacy`](./packages/node-legacy.md))
30-
31-
1:1 matches for Node.js's original documentation tooling, for consumers of
32-
the classic layouts.
33-
34-
| Target | Output |
35-
| ---------------------------------------------------- | ------------------------------ |
36-
| [`legacy-json`](./generators/legacy-json.md) | The classic per-document JSON. |
37-
| [`legacy-json-all`](./generators/legacy-json-all.md) | The single-file JSON bundle. |
38-
3929
### Node.js-specific ([`@node-core/doc-kit`](./packages/node.md))
4030

4131
Outputs consumed by the Node.js project's own build and release processes.

‎docs/index.md‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -8,7 +8,7 @@ on [the OpenJS Slack][].
88

99
A few places `doc-kit` is already in use. Feel free to PR yours.
1010

11-
- <https://nodejs.org/api> - `html`, `section-pages`, `legacy-json`
11+
- <https://nodejs.org/api> - `html`, `section-pages`
1212
- <https://nodejs.org/llms.txt> - `llms-txt`
1313
- <https://beta.docs.nodejs.org/> - `html`, `orama-db`, `llms-txt`
1414
- <https://nodejs.org/learn> - `html`, `orama-db`, `llms-txt`

‎packages/core/README.md‎

Lines changed: 4 additions & 5 deletions
Original file line numberDiff line numberDiff line change
@@ -13,11 +13,10 @@ Output formats are provided by generators. This package ships the shared
1313
pipeline stages and the JSON generators (`json`, `json-all`, and the
1414
debugging-only `json-simple`); the rest come from companion packages:
1515

16-
| Package | Generators |
17-
| -------------------------------------------------------------------------------------- | ----------------------------------------------------------- |
18-
| [`@doc-kit/generator-react`](https://www.npmjs.com/package/@doc-kit/generator-react) | `html` (the modern site), `orama-db`, `llms-txt`, `sitemap` |
19-
| [`@node-core/doc-kit-legacy`](https://www.npmjs.com/package/@node-core/doc-kit-legacy) | `legacy-json`, `legacy-json-all` (Node.js-specific) |
20-
| [`@node-core/doc-kit`](https://www.npmjs.com/package/@node-core/doc-kit) | `man-page`, `api-links`, `addon-verify` (Node.js-specific) |
16+
| Package | Generators |
17+
| ------------------------------------------------------------------------------------ | ----------------------------------------------------------- |
18+
| [`@doc-kit/generator-react`](https://www.npmjs.com/package/@doc-kit/generator-react) | `html` (the modern site), `orama-db`, `llms-txt`, `sitemap` |
19+
| [`@node-core/doc-kit`](https://www.npmjs.com/package/@node-core/doc-kit) | `man-page`, `api-links`, `addon-verify` (Node.js-specific) |
2120

2221
Custom generators load by import specifier — any module whose default export
2322
is a generator works as a `--target`.

0 commit comments

Comments
 (0)