fix(docs): pin builddocs to 1.x to fix api docs build

[Saul-Mirone]

• I read the contributing guide
• I agree to follow the code of conduct

Summary

pnpm -F @milkdown/docs run build currently fails for every module with:

TypeError: (0 , import_builddocs.build) is not a function
    at docs/src/index.ts:45:26

Root cause: #2404 ("bump up all dependencies") upgraded builddocs from ^1.0.8 to ^2.0.0. builddocs 2.x is an incompatible rewrite — the build({ name, filename, main, format, templates }) function was replaced by buildDocs({ modules, renderMarkdown, ... }), which emits HTML (ModuleDocs[].text = builder.html) and drops both the markdown output (format: 'markdown') and the templates mechanism the docs script relies on to generate docs/lib/*.md. Migrating to 2.x would change the generated output from markdown to HTML and require rewriting the consumers — out of scope for a build fix.

This PR also fixes why CI never caught the break: the docs build already runs in the build job (via pnpm -r run build), but docs/src/index.ts logged each module failure and then resolved anyway, so the process exited 0 even when all 24 modules failed.

Changes

• docs/package.json: pin builddocs ^2.0.0 → ^1.0.9 (restores the markdown-producing 1.x API).
• .github/renovate.json: block builddocs major upgrades so it isn't auto-bumped back to the incompatible 2.x (patches within 1.x still flow).
• docs/src/index.ts: exit non-zero when any module fails to build, so a broken build actually fails instead of silently exiting 0.
• docs/api/preset-commonmark.md: add @sanitizeLinkHref to the template — a public export added in fix: sanitize unsafe link hrefs and emoji html to prevent stored XSS #2410 that was missing from the doc template (previously logged Item sanitizeLinkHref is missing from the doc template).
• .github/workflows/ci.yml: run the api docs build as an explicit, named step in the build job so regressions are caught going forward.
• pnpm-lock.yaml: relock.

How did you test this change?

Success path — all modules build, exit 0:

$ pnpm -F @milkdown/docs run build
...
[docs] Build module: @milkdown/transformer finished.
[docs] Build api done.
$ echo $?
0

No more sanitizeLinkHref warning, and it renders in the output:

$ grep -n sanitizeLinkHref docs/lib/preset-commonmark.md
393: #### sanitizeLinkHref `(href: unknown) → string`

Failure now actually fails (temporarily broke the template dir to force it):

[docs] Build api failed: 24 module(s) could not be built.
$ echo $?
1

oxlint and tsc -b docs/tsconfig.json both pass clean.

[vercel]

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

Project	Deployment	Actions	Updated (UTC)
milkdown-storybook	Ready	Preview	Aug 3, 2026 11:42am

[changeset-bot]

⚠️ No Changeset found

Latest commit: 2d3a254

Merging this PR will not cause a version bump for any packages. If these changes should not result in a new version, you're good to go. If these changes should result in a version bump, you need to add a changeset.

This PR includes no changesets

When changesets are added to this PR, you'll see the packages that this PR includes changesets for and the associated semver types

Click here to learn what changesets are, and how to add one.

Click here if you're a maintainer who wants to add a changeset to this PR

[Copilot]

Pull request overview

This PR fixes the @milkdown/docs API docs build by reverting builddocs back to the compatible 1.x API (which provides build({ ... , format: 'markdown', templates })) and preventing Renovate from proposing future major upgrades that would break the current markdown/template-based docs generation.

Changes:

• Pin docs workspace builddocs dependency from ^2.x back to ^1.0.9 (keeps <2.0.0).
• Add a Renovate package rule to disable major updates for builddocs.
• Update pnpm-lock.yaml to reflect the builddocs@1.0.9 dependency graph.

Reviewed changes

Copilot reviewed 2 out of 3 changed files in this pull request and generated no comments.

File	Description
docs/package.json	Pins builddocs to the 1.x line required by the current docs build script.
.github/renovate.json	Adds a Renovate rule to block builddocs major upgrades that would break the markdown/templates workflow.
pnpm-lock.yaml	Re-locks dependencies to builddocs@1.0.9 and its transitive deps.

Files not reviewed (1)

• pnpm-lock.yaml: Generated file

---

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.

[pkg-pr-new]

Open in StackBlitz

@milkdown/components

npm i https://pkg.pr.new/@milkdown/components@2442

@milkdown/core

npm i https://pkg.pr.new/@milkdown/core@2442

@milkdown/crepe

npm i https://pkg.pr.new/@milkdown/crepe@2442

@milkdown/ctx

npm i https://pkg.pr.new/@milkdown/ctx@2442

@milkdown/exception

npm i https://pkg.pr.new/@milkdown/exception@2442

@milkdown/kit

npm i https://pkg.pr.new/@milkdown/kit@2442

@milkdown/prose

npm i https://pkg.pr.new/@milkdown/prose@2442

@milkdown/transformer

npm i https://pkg.pr.new/@milkdown/transformer@2442

@milkdown/utils

npm i https://pkg.pr.new/@milkdown/utils@2442

@milkdown/react

npm i https://pkg.pr.new/@milkdown/react@2442

@milkdown/vue

npm i https://pkg.pr.new/@milkdown/vue@2442

@milkdown/plugin-automd

npm i https://pkg.pr.new/@milkdown/plugin-automd@2442

@milkdown/plugin-block

npm i https://pkg.pr.new/@milkdown/plugin-block@2442

@milkdown/plugin-clipboard

npm i https://pkg.pr.new/@milkdown/plugin-clipboard@2442

@milkdown/plugin-collab

npm i https://pkg.pr.new/@milkdown/plugin-collab@2442

@milkdown/plugin-cursor

npm i https://pkg.pr.new/@milkdown/plugin-cursor@2442

@milkdown/plugin-diff

npm i https://pkg.pr.new/@milkdown/plugin-diff@2442

@milkdown/plugin-emoji

npm i https://pkg.pr.new/@milkdown/plugin-emoji@2442

@milkdown/plugin-highlight

npm i https://pkg.pr.new/@milkdown/plugin-highlight@2442

@milkdown/plugin-history

npm i https://pkg.pr.new/@milkdown/plugin-history@2442

@milkdown/plugin-indent

npm i https://pkg.pr.new/@milkdown/plugin-indent@2442

@milkdown/plugin-listener

npm i https://pkg.pr.new/@milkdown/plugin-listener@2442

@milkdown/plugin-prism

npm i https://pkg.pr.new/@milkdown/plugin-prism@2442

@milkdown/plugin-slash

npm i https://pkg.pr.new/@milkdown/plugin-slash@2442

@milkdown/plugin-streaming

npm i https://pkg.pr.new/@milkdown/plugin-streaming@2442

@milkdown/plugin-tooltip

npm i https://pkg.pr.new/@milkdown/plugin-tooltip@2442

@milkdown/plugin-trailing

npm i https://pkg.pr.new/@milkdown/plugin-trailing@2442

@milkdown/plugin-upload

npm i https://pkg.pr.new/@milkdown/plugin-upload@2442

@milkdown/preset-commonmark

npm i https://pkg.pr.new/@milkdown/preset-commonmark@2442

@milkdown/preset-gfm

npm i https://pkg.pr.new/@milkdown/preset-gfm@2442

@milkdown/theme-nord

npm i https://pkg.pr.new/@milkdown/theme-nord@2442

commit: 2d3a254

[Copilot]

Pull request overview

Copilot reviewed 5 out of 6 changed files in this pull request and generated no new comments.

Files not reviewed (1)

• pnpm-lock.yaml: Generated file

Suppressed comments (1)

.github/workflows/ci.yml:69

• The new "Build API docs" step duplicates work: pnpm build already runs pnpm -r run build (root package.json), which includes @milkdown/docs's build script. Now that docs/src/index.ts sets a non-zero exit code on failure, the existing pnpm build step should already fail CI when docs generation breaks. Consider either removing this extra step, or adjusting the earlier build step to exclude docs so it only runs once.

      - name: Build packages
        run: pnpm build

      - name: Build API docs
        run: pnpm --filter=@milkdown/docs run build