fix(metadata): keep hyphens in heading slugs like the old doc tooling by ovflowd · Pull Request #1232 · nodejs/doc-kit

ovflowd · 2026-11-01T21:49:17Z

Description

This PR makes heading anchors match the old Node.js doc tooling again, by dropping the three hyphen rules from DOC_API_SLUGS_REPLACEMENTS.

#610 swapped the --+ collapse for /^(?!-)(?!-+$).*?(--+)/, which also swallows everything before the first run of hyphens. That's how nodejs.org/api ends up serving #-check for -c, --check. The old tooling (getId in tools/doc/html.mjs) never collapsed or trimmed hyphens at all: it lowercased, dropped punctuation and turned spaces into hyphens, which is what github-slugger already does. So rather than fixing the collapse, this stops post-processing hyphens.

Heading	v24 docs (old tooling)	`main`	This PR
`-c`, `--check`	`#-c---check`	`#-check`	`#-c---check`
`new ReadableStream([underlyingSource [, strategy]])`	`#new-readablestreamunderlyingsource--strategy`	`#-strategy`	`#new-readablestreamunderlyingsource--strategy`

It's the same drift #757 reported for -- flags, which #810 fixed for that one case. The slugger tests now pin the old tooling's behaviour; the ones they replace came from #676 and captured #610's output (foo--bar → -bar).

Validation

node --run test (782 tests), node --run lint and node --run format:check pass.
Over all 5,809 headings in nodejs/node's doc/api, the slugs now match the old getId exactly. On main, 18 of them differ.
Generating cli.md with legacy-html gives #-c---check and #-e---eval-script, as in the v24 docs.

Opening cli.html#-c---check, the v24 anchor, in a legacy-html build of cli.md:

`main`	This PR

Related Issues

Refs: #757, #610

Check List

I have read the Contributing Guidelines and made commit messages that follow the guideline.
I have run node --run test and all tests passed.
I have check code formatting with node --run format:check & node --run lint.

#610 replaced the `--+` collapse with `/^(?!-)(?!-+$).*?(--+)/`, which also swallows everything before the first run of hyphens, so headings lost their prefix: `-c`, `--check` became `#-check` and `DEP0062: node --debug` became `#-debug`. nodejs.org/api serves those anchors today. The old tooling (getId in tools/doc/html.mjs) never collapsed or trimmed hyphens: it lowercased, dropped punctuation and turned spaces into hyphens, which is what github-slugger already does. Dropping the three hyphen rules matches its anchors for all 5809 headings in doc/api, where the current rules differ on 18 of them. That's the same drift #757 reported for `--` flags, which #810 fixed for that one case. Assisted-by: Claude Opus 5.5 <noreply@anthropic.com>

vercel · 2026-11-01T21:49:19Z

The latest updates on your projects. Learn more about Vercel for GitHub.

Project	Deployment	Actions	Updated
api-docs-tooling	Ready	Preview	Nov 1, 2026 9:49pm UTC

cloudflare-workers-and-pages · 2026-11-01T21:49:59Z

🚀 Deploying Preview to Cloudflare 🚀

Preview Deployments by commit

Status	Deployment URL	Commit	Updated (UTC)	See this deployment's details
Build: Success ✅ View logs ↗	No Preview URL. Enable ↗	`36e28ff`	2026-11-01T21:50:00.627Z	View logs ↗

codecov · 2026-11-01T21:50:14Z

Codecov Report

✅ All modified and coverable lines are covered by tests.
✅ Project coverage is 94.14%. Comparing base (7e6bf44) to head (36e28ff).

Additional details and impacted files

@@            Coverage Diff             @@
##             main    #1232      +/-   ##
==========================================
- Coverage   94.14%   94.14%   -0.01%     
==========================================
  Files         291      291              
  Lines       28942    28934       -8     
  Branches     2942     2938       -4     
==========================================
- Hits        27248    27240       -8     
  Misses       1672     1672              
  Partials       22       22

☔ View full report in Codecov by Harness.
📢 Have feedback on the report? Share it here.

🚀 New features to boost your workflow:

📦 JS Bundle Analysis: Save yourself from yourself by tracking and limiting bundle sizes in JS merges.

github-actions · 2026-11-01T21:50:54Z

`api-links` Generator

Performance estimate _{(single CI run)}

Generation time: 3.1% slower (970.00 ms → 1.00 s)
Peak memory: 1.5% higher (288.97 MB → 293.35 MB)

`json` Generator

Output: 6 files differ

buffer.json

Expected values to be strictly deep-equal:
+ actual - expected
... Skipped lines

  {
    '$schema': 'https://doc-kit.nodejs.org/schemas/api-doc/1.0.1.json',
    added: [],
    changes: [],
    children: [
...
            ],
+           id: 'the---zero-fill-buffers-command-line-option',
-           id: '-zero-fill-buffers-command-line-option',
            kind: 'section',
            name: 'The --zero-fill-buffers command-line option',
            napiVersion: [],
            overloadOf: null,
            removed: [],

cli.json

Expected values to be strictly deep-equal:
+ actual - expected
... Skipped lines

  {
    '$schema': 'https://doc-kit.nodejs.org/schemas/api-doc/1.0.1.json',
    added: [],
    changes: [],
    children: [
...
            examples: [],
+           id: '-c---check',
-           id: '-check',
            kind: 'section',
            name: '-c, --check',
            napiVersion: [],
            overloadOf: null,
            removed: [],
...
            ],
+           id: '-c-condition---conditionscondition',
-           id: '-conditionscondition',
            kind: 'section',
            name: '-C condition, --conditions=condition',
            napiVersion: [],
            overloadOf: null,
            removed: [],
...
            examples: [],
+           id: '-e---eval-script',
-           id: '-eval-script',
            kind: 'section',
            name: '-e, --eval "script"',
            napiVersion: [],
            overloadOf: null,
            removed: [],
...
            examples: [],
+           id: '-h---help',
-           id: '-help',
            kind: 'section',
            name: '-h, --help',
            napiVersion: [],
            overloadOf: null,
            removed: [],
...
            examples: [],
+           id: '-i---interactive',
-           id: '-interactive',
            kind: 'section',
            name: '-i, --interactive',
            napiVersion: [],
            overloadOf: null,
            removed: [],
...
            examples: [],
+           id: '-p---print-script',
-           id: '-print-script',
            kind: 'section',
            name: '-p, --print "script"',
            napiVersion: [],
            overloadOf: null,
            removed: [],
...
            examples: [],
+           id: '-r---require-module',
-           id: '-require-module',
            kind: 'section',
            name: '-r, --require module',
            napiVersion: [],
            overloadOf: null,
            removed: [],
...
            examples: [],
+           id: '-v---version',
-           id: '-version',
            kind: 'section',
            name: '-v, --version',
            napiVersion: [],
            overloadOf: null,
            removed: [],

module.json

Expected values to be strictly deep-equal:
+ actual - expected
... Skipped lines

  {
    '$schema': 'https://doc-kit.nodejs.org/schemas/api-doc/1.0.1.json',
    added: [],
    changes: [],
    children: [
...
                examples: [],
+               id: 'new-sourcemappayload--linelengths-',
-               id: '-linelengths',
                kind: 'constructor',
                name: 'SourceMap',
                napiVersion: [],
                overloadOf: null,
                removed: [],

single-executable-applications.json

Expected values to be strictly deep-equal:
+ actual - expected
... Skipped lines

  {
    '$schema': 'https://doc-kit.nodejs.org/schemas/api-doc/1.0.1.json',
    added: [
      'v19.7.0',
      'v18.16.0'
...
        ],
+       id: 'generating-single-executable-applications-with---build-sea',
-       id: '-build-sea',
        kind: 'section',
        name: 'Generating single executable applications with --build-sea',
        napiVersion: [],
        overloadOf: null,
        removed: [],

tls.json

Expected values to be strictly deep-equal:
+ actual - expected
... Skipped lines

  {
    '$schema': 'https://doc-kit.nodejs.org/schemas/api-doc/1.0.1.json',
    added: [],
    changes: [],
    children: [
...
            examples: [],
+           id: 'using---tls-cipher-list',
-           id: '-tls-cipher-list',
            kind: 'section',
            name: 'Using --tls-cipher-list',
            napiVersion: [],
            overloadOf: null,
            removed: [],

webstreams.json

Expected values to be strictly deep-equal:
+ actual - expected
... Skipped lines

  {
    '$schema': 'https://doc-kit.nodejs.org/schemas/api-doc/1.0.1.json',
    added: [
      'v16.5.0'
    ],
...
                examples: [],
+               id: 'new-readablestreamunderlyingsource--strategy',
-               id: '-strategy',
                kind: 'constructor',
                name: 'ReadableStream',
                napiVersion: [],
                overloadOf: null,
                removed: [],

Performance estimate _{(single CI run)}

Generation time: 35.5% faster (9.47 s → 6.11 s)
Peak memory: 3.0% higher (992.50 MB → 1022.34 MB)

`legacy-html` Generator

Output size: 6 files changed · net +636.00 B

File size details

File	Main	PR	Change
`single-executable-applications.html`	127.78 KB	127.97 KB	+192.00 B (+0.1%)
`cli.html`	372.69 KB	372.85 KB	+168.00 B (+0.0%)
`webstreams.html`	297.01 KB	297.15 KB	+140.00 B (+0.0%)
`module.html`	364.54 KB	364.63 KB	+88.00 B (+0.0%)
`tls.html`	297.30 KB	297.33 KB	+28.00 B (+0.0%)
`buffer.html`	1.17 MB	1.17 MB	+20.00 B (+0.0%)

Performance estimate _{(single CI run)}

Generation time: 0.3% slower (16.46 s → 16.51 s)
Peak memory: 3.7% higher (1.46 GB → 1.52 GB)

`legacy-json` Generator

Performance estimate _{(single CI run)}

Generation time: 10.9% faster (8.10 s → 7.22 s)
Peak memory: 4.6% higher (916.79 MB → 959.26 MB)

`llms-txt` Generator

Performance estimate _{(single CI run)}

Generation time: 17.8% faster (6.40 s → 5.26 s)
Peak memory: 4.1% higher (957.82 MB → 997.05 MB)

`orama-db` Generator

Output size: 1 file changed · net +2.89 KB

File size details

File	Main	PR	Change
`orama-db.json`	29.66 MB	29.67 MB	+2.89 KB (+0.0%)

Performance estimate _{(single CI run)}

Generation time: 14.2% slower (8.04 s → 9.18 s)
Peak memory: 4.3% lower (1.09 GB → 1.04 GB)

`web` Generator

Output size: 7 files changed · net +1.02 KB

File size details

File	Main	PR	Change
`all.html`	34.78 MB	34.78 MB	+522.00 B (+0.0%)
`single-executable-applications.html`	170.64 KB	170.83 KB	+192.00 B (+0.1%)
`cli.html`	678.78 KB	678.95 KB	+168.00 B (+0.0%)
`webstreams.html`	565.36 KB	565.43 KB	+70.00 B (+0.0%)
`module.html`	533.05 KB	533.09 KB	+44.00 B (+0.0%)
`tls.html`	550.15 KB	550.17 KB	+28.00 B (+0.0%)
`buffer.html`	1.82 MB	1.82 MB	+20.00 B (+0.0%)

Performance estimate _{(single CI run)}

Generation time: 23.6% faster (20.14 s → 15.39 s)
Peak memory: 3.5% higher (1.48 GB → 1.53 GB)

btea · 2026-11-03T08:47:27Z

#1232 (comment) Is there a way to generate a preview link for this PR's edits in the comments here?

ovflowd requested a review from a team as a code owner November 1, 2026 21:49

vercel Bot deployed to Preview – api-docs-tooling November 1, 2026 21:49

View deployment

AugustinMauroy approved these changes Nov 2, 2026

View reviewed changes

btea approved these changes Nov 2, 2026

View reviewed changes

Navigation Menu

Repository navigation

fix(metadata): keep hyphens in heading slugs like the old doc tooling - #1232

fix(metadata): keep hyphens in heading slugs like the old doc tooling#1232
ovflowd wants to merge 1 commit into
mainfrom
fix/slug-collapse-hyphens

ovflowd commented Nov 1, 2026 •

edited

Loading

Uh oh!

vercel Bot commented Nov 1, 2026 •

edited

Loading

Uh oh!

cloudflare-workers-and-pages Bot commented Nov 1, 2026 •

edited

Loading

Uh oh!

codecov Bot commented Nov 1, 2026 •

edited

Loading

Uh oh!

github-actions Bot commented Nov 1, 2026

Uh oh!

btea commented Nov 3, 2026

Uh oh!

This branch was successfully deployed

Reviewers

Uh oh!

Assignees

Labels

Projects

Milestone

Development

Uh oh!

3 participants

Conversation

ovflowd commented Nov 1, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Description

Validation

Related Issues

Check List

Uh oh!

vercel Bot commented Nov 1, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

cloudflare-workers-and-pages Bot commented Nov 1, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

🚀 Deploying Preview to Cloudflare 🚀

Preview Deployments by commit

Uh oh!

codecov Bot commented Nov 1, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Codecov Report

Uh oh!

github-actions Bot commented Nov 1, 2026

api-links Generator

json Generator

legacy-html Generator

legacy-json Generator

llms-txt Generator

orama-db Generator

web Generator

Uh oh!

btea commented Nov 3, 2026

Uh oh!

This branch was successfully deployed

Reviewers

Uh oh!

Assignees

Labels

Projects

Milestone

Development

Uh oh!

3 participants

ovflowd commented Nov 1, 2026 •

edited

Loading

vercel Bot commented Nov 1, 2026 •

edited

Loading

cloudflare-workers-and-pages Bot commented Nov 1, 2026 •

edited

Loading

codecov Bot commented Nov 1, 2026 •

edited

Loading

`api-links` Generator

`json` Generator

`legacy-html` Generator

`legacy-json` Generator

`llms-txt` Generator

`orama-db` Generator

`web` Generator