build(docs): render Markdown with Sätteri and drop the remark plugin

[chhoumann]

Summary

Astro 7's default Markdown processor, Sätteri, supports custom heading ids (## Heading {#custom-id}) natively through its headingAttributes feature. That's the only thing our custom remark plugin did. So this PR switches the docs site to Sätteri and deletes the plugin and the whole remark stack it needed. The site renders the same.

Changes

• astro.config.mjs: markdown.processor: satteri({ features: { headingAttributes: true } }).
• Deleted plugins/remark-heading-id.mjs, including its workaround for smartypants turning -- in ids into dashes. Sätteri reads heading attributes before smart punctuation runs, so ids like ai--online come through as written.
• Dependencies: @astrojs/markdown-remark and unist-util-visit are replaced by @astrojs/markdown-satteri (already in the tree via Astro and Starlight).
• Lockfile regenerated from scratch. That's the only reproducible way to drop packages that were kept only because the old lockfile listed them as optional peers.
  • 57 fewer packages (469 → 412): the remark/MDX compile stack (@mdx-js/mdx, estree/recma/retext, rehype-raw, remark-smartypants, …) and an unused optional typescript peer.
  • No new package names. The re-resolve also picks up patch releases within the existing ranges: @astrojs/starlight 0.42.0 → 0.42.3 (a desktop sidebar popover fix and a TOC freeze fix for PageTitle overrides), plus small transitive patches (verkit, undici, devalue, …).
• README: layout note updated. The zod note now names the importer that makes the pin necessary.

The zod pin stays. I tested removing it by putting a booby-trapped zod in the parent node_modules, and the build loaded it: Astro's prerender bundle imports zod/v4 from the project root.

Testing / validation

Clean node_modules, Node 22.23.2, pnpm install --frozen-lockfile && pnpm run build, compared against master ce44a43b:

• Exit 0, 52 pages. Build warnings are the same as master's (only Starlight's i18n and 404 warnings).
• scripts/check-links.py: 0 problems. All 313 {#id} markers render as ids, with none left in the text.
• Rendered DOM (parsed, entities decoded): the same on every page, apart from:
  • Sätteri's equivalent serialization: bare data-pagefind-ignore instead of ="", a raw <br /> instead of <br>, and whitespace between block tags.
  • Starlight 0.42.3's version string and its sidebar and TOC scripts.
• Pixels: full-length screenshots of all 51 pages at 1440px are identical to master. The only differing pixels are inside four animated GIFs (Readwise, MoveNotes, Suggester and AI Assistant pages), which were captured on different frames.
• Mobile: menu closed, menu open, resize to desktop and back are all pixel-identical to master, and on desktop the sidebar no longer carries a popover attribute (the 0.42.1 fix). No JS errors.
• Search: the index is unchanged apart from whitespace. It's slightly better, since table cells were previously glued together ("ContextAccess pattern" is now "Context Access pattern", so words in tables match).
• llms.txt, llms-small.txt, llms-full.txt, every .md endpoint, docs-index.json, sitemap, _redirects and _headers: byte-identical.
• astro dev: anchors and asides render.
• pnpm dedupe --check is clean.

Checklist

• PR title follows Conventional Commits. build(docs) does not trigger a release.
• Linked any related issue(s): follow-up to build: bump the docs-dependencies group in /docs with 3 updates #1778 / build(docs): pass remark plugins via unified() and dedupe lockfile #1782.
• Noted release/migration impact: none. Docs site only; URLs and anchors are unchanged.

Note

Switch docs Markdown renderer to Sätteri and remove remark-heading-id plugin

• Replaces the unified remark processor in astro.config.mjs with the Sätteri processor and enables Sätteri heading attributes to keep custom heading IDs working without the local plugin.
• Deletes the standalone plugin at remark-heading-id.mjs that previously detected custom heading-ID markers and normalized smartypants dashes.
• Swaps @astrojs/markdown-remark for @astrojs/markdown-satteri and drops the direct unist-util-visit dependency in package.json, with matching lockfile updates.
• Updates README.md to document Sätteri as the renderer and heading attributes support.
• Risk: Sätteri's heading-ID and dash-handling behavior may differ from the deleted plugin; verify generated heading anchors and dash output in rendered docs.

^{Macroscope summarized 772699d.}

Summary by CodeRabbit

• Documentation

  • Updated the documentation build to use the Sätteri Markdown processor.
  • Custom heading anchors, such as ## Heading {#custom-id}, continue to work.
  • Clarified the documentation’s dependency and troubleshooting notes.

• Refactor

  • Removed the previous custom heading-anchor processing and its associated tooling.
  • Simplified Markdown configuration while preserving existing heading-anchor behavior.

[chatgpt-codex-connector]

You have reached your Codex usage limits for code reviews. You can see your limits in the Codex usage dashboard.
To continue using code reviews, add credits to your account and enable them for code reviews in your settings.

[coderabbitai]

Navigate logical layers of code changes, visualize relationships, and explore their blast radius.

No actionable comments were generated in the recent review. 🎉

ℹ️ Recent review info

⚙️ Run configuration

Configuration used: Organization UI

Review profile: CHILL

Plan: Advanced

Run ID: 1c79a2b4-ceb0-43c7-b4ed-00297a614f53

📥 Commits

Reviewing files that changed from the base of the PR and between ce44a43 and 772699d.

⛔ Files ignored due to path filters (1)

• docs/pnpm-lock.yaml is excluded by !**/pnpm-lock.yaml

📒 Files selected for processing (4)

• docs/README.md
• docs/astro.config.mjs
• docs/package.json
• docs/plugins/remark-heading-id.mjs

💤 Files with no reviewable changes (1)

• docs/plugins/remark-heading-id.mjs

Included review availability: Your plan provides up to 8 included reviews per hour; 7 remain after this review.

---

📝 Walkthrough

Walkthrough

The documentation site replaces the local heading ID plugin with Sätteri's headingAttributes feature. It updates dependencies and documents the remaining zod resolution behavior.

Changes

Markdown processor migration

Layer / File(s)	Summary
Sätteri heading support docs/package.json, docs/astro.config.mjs, docs/plugins/remark-heading-id.mjs, docs/README.md	The site uses @astrojs/markdown-satteri with headingAttributes enabled. The local remarkHeadingId plugin and its dependency are removed. The documentation describes the new anchor handling.
Dependency documentation update docs/README.md	The dependency note lists zod and describes zod/v4 resolution from the parent repository's node_modules.

Priority: ⬇️ Low

Estimated code review effort: 2 (Simple) | ~10 minutes

Change: Refactor

Merge Risk: ⚪ Minimal · up to 77269

The migration preserves documented heading anchors and introduces no merge-blocking risk.

🚥 Pre-merge checks | ✅ 5

✅ Passed checks (5 passed)

Check name	Status	Explanation
Description Check	✅ Passed	Check skipped - CodeRabbit’s high-level summary is enabled.
Title check	✅ Passed	The title clearly summarizes the main changes: it switches the docs site to Sätteri for Markdown rendering and removes the custom remark plugin.
Docstring Coverage	✅ Passed	No functions found in the changed files to evaluate docstring coverage. Skipping docstring coverage check. Docstring coverage is scoped to functions touched by this diff. Analyzed 0 functions across 1…
Linked Issues check	✅ Passed	Check skipped because no linked issues were found for this pull request.
Out of Scope Changes check	✅ Passed	Check skipped because no linked issues were found for this pull request.

✨ Finishing Touches

📝 Generate docstrings

• Commit to this branch
• Create a new PR

🧪 Generate unit tests (beta)

• Commit to this branch
• Create a new PR

---

Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out.

❤️ Share

• X
• Mastodon
• Reddit
• LinkedIn

_{A rabbit hops through markdown bright
Sätteri makes the headings right
Old plugins rest beneath the tree
New anchors bloom with clarity
Dependencies grow light and neat}

_{Comment @coderabbitai help to get the list of available commands.}

[cloudflare-workers-and-pages]

Deploying quickadd with    Cloudflare Pages

Latest commit:	772699d
Status:	✅  Deploy successful!
Preview URL:	https://203bc368.quickadd.pages.dev
Branch Preview URL:	https://build-docs-satteri.quickadd.pages.dev

View logs