perf(site): migrate markdown pipeline to Sätteri#1733
Open
decepulis wants to merge 5 commits into
Open
Conversation
Flip `markdown.processor` from the `unified()` parity bridge to Astro 7's native Rust processor, Sätteri, and port the custom transforms to Sätteri MDAST plugins: - satteriReadingTime / satteriConditionalHeadings: factories writing `ctx.data.astro.frontmatter.*` (surfaced unchanged as `render().remarkPluginFrontmatter`). - satteriCodeFrame: wraps standalone fenced code in a new `<CodeFrame>` component, since under Sätteri the Shiki highlight step rewrites `<pre>` to raw HTML before HAST plugins run, so the old `pre`/`code` overrides no longer fire. CodeFrame reuses the existing Tabs chrome + CopyButton; the raw `.astro-code` <pre> gets its monospace font/size from a CSS rule. Title is read from fence meta, retiring shikiTransformMetadata. Shiki themes/langs/notation transformers carry over via `shikiConfig` (processor-independent); GFM + SmartyPants stay on by Astro defaults. Drops @astrojs/markdown-remark, mdast-util-to-string, unist-util-visit; adds satteri + @astrojs/markdown-satteri. Includes unit tests for the three MDAST plugins and updates site/CLAUDE.md. Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_018fACaXD786B35idFc1yUhW
✅ Deploy Preview for vjs10-site ready!
To edit notification comments on pull requests, go to your Netlify project configuration. |
|
The latest updates on your projects. Learn more about Vercel for GitHub.
|
Contributor
📦 Bundle Size Report🎨 @videojs/html — no changesPresets (7)
Media (10)
Players (5)
Skins (30)
UI Components (38)
Sizes are marginal over the root entry point. ⚛️ @videojs/react — no changesPresets (7)
Media (9)
Skins (27)
UI Components (32)
Sizes are marginal over the root entry point. 🧩 @videojs/core — no changesEntries (14)
🏷️ @videojs/element — no changesEntries (2)
📦 @videojs/store — no changesEntries (3)
🔧 @videojs/utils — no changesEntries (10)
📦 @videojs/spf — no changesEntries (4)
ℹ️ How to interpretJS sizes are initial static graph totals (minified + brotli). Lazy dynamic chunks are shown separately when present.
Run |
`astro check` is stricter than the project's tsgo typecheck and flagged type-only issues the latter missed: - Cast the parsed reference JSON to the model's parameter type (the old `.js` plugin was unchecked) and pass `partOrder ?? undefined`. - Type the code-frame ancestor walk var to admit `undefined`. - Seed the full `data.astro` shape (incl. localImagePaths/remoteImagePaths) in the plugin tests to match the markdown-satteri DataMap augmentation. Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_018fACaXD786B35idFc1yUhW
The Sätteri migration added `.astro-code { font-size: var(--text-code) }`
to restore monospace sizing for raw highlighted `<pre>`. But `--text-code`
is an `em`, and the React `Code` components (`shared.pre` = "shiki
astro-code") also put `text-code` on their inner `<code>`. Sizing the
`<pre>` as well compounded the two `em`s (0.875 × 0.875), shrinking that
code to ~12.25px next to the 14px MDX blocks.
Move the size onto `.astro-code code` so it applies to the code element
once, matching the pre-Sätteri output where MarkdownCode sized `<code>`
directly. Verified all code blocks render uniformly at 14px.
Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_018fACaXD786B35idFc1yUhW
… control Astro's Shiki highlighter writes an inline style on each highlighted `<pre>` (theme background/color plus `overflow-x: auto`). Pre-Sätteri, `Pre.astro` deliberately discarded that style so the surrounding frame owned the background and scrolling — Shiki highlighted the text, the container was ours. Under Sätteri the pre is slotted as raw HTML, so the inline style survived: code blocks gained their own scroll box inset inside the frame padding instead of scrolling at the container. Add a Shiki `pre` transformer that deletes the inline style. Astro appends its built-in transformer first, so ours runs last and removes the fully-assembled style. Token colors live on the inner spans and are unaffected; the React `Code` components already rebuild their own `<pre>`, so only the markdown/MDX path needed this. Verified the built `<pre>` now matches main (class + tabindex + data-language, no style). Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_018fACaXD786B35idFc1yUhW
decepulis
commented
Jun 24, 2026
decepulis
left a comment
decepulis
left a comment
Collaborator
Author
There was a problem hiding this comment.
mostly just nits about what goes in the comments. please address and then mark as ready for review.
Collaborator
Author
There was a problem hiding this comment.
This file requires a larger cleanup, but I'm considering that out of scope for this PR
Address review: comments should explain what the code does or why it's unusual for future maintainers, not narrate the migration. Remove references to the prior remark/rehype plugins, `Pre.astro`, and the old processor across the Sätteri plugins, `CodeFrame`, `MarkdownCode`, the shiki-transformers CSS, and the Astro config; tighten the wording. Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_018fACaXD786B35idFc1yUhW
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
2 participants
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Previously, Astro used
unifiedto do its markdown processing. Now it suggests rust-basedsatteri.This PR migrates our unified plugins to satteri and works around some new satteri idioms. We relied heavily on unified plugins for some MDX magic, so, this PR isn't trivial.
Visually, output is identical, though, so I think we succeeded.
The deets
Here's what's new
remarkReadingTimesatteriReadingTimectx.data.astro.frontmatter.{minutesRead,readingTimeMinutes}remarkConditionalHeadingssatteriConditionalHeadingsfrontmatter.conditionalHeadingsrehypePrepareCodeBlockssatteriCodeFrameshikiTransformMetadataCode blocks
Satteri runs at a different time than unified did, so we needed to apply code block styling differently. Here's how Claude would explain that:
Under Sätteri the Shiki highlight step rewrites each
<pre>to raw HTML before HAST plugins run, so the oldpre/codecomponent overrides no longer fire for code blocks. Instead,satteriCodeFramewraps each standalone fenced block in a new<CodeFrame>component at the MDAST stage (blocks inside an authored<TabsPanel>are left alone).CodeFrame.astroreuses the existingTabschrome +CopyButton, and the raw.astro-code<pre>gets its monospace font/size from a rule inshiki-transformers.css(previously supplied byMarkdownCode'scodeBlockbranch).Pre.astrois removed;MarkdownCodeis simplified to inline-only.Closes #1719.
Generated by Claude Code
Note
Medium Risk
Touches all MDX/Markdown rendering (TOC anchors, reading time, code frames); regressions would be site-wide but behavior is intended to be visually identical and covered by new plugin tests.
Overview
Switches the docs site from the unified (
@astrojs/markdown-remark) Markdown processor to Sätteri via@astrojs/markdown-satteri, wiring three new MDAST plugins inastro.config.mjs: reading time, conditional TOC headings, and code-block framing.Plugin parity:
remarkReadingTime/remarkConditionalHeadings/rehypePrepareCodeBlocksandshikiTransformMetadataare removed and replaced bysatteriReadingTime,satteriConditionalHeadings, andsatteriCodeFrame, still writing the sameremarkPluginFrontmatterfields (minutesRead,conditionalHeadings, etc.). Shiki notation transformers stay;shikiStripPreStylereplaces the title transformer and strips inline<pre>styles soCodeFrameowns chrome.Code blocks: Because Sätteri emits highlighted
<pre>as raw HTML before HAST/component overrides run, standalone fences are wrapped at MDAST in<CodeFrame>(Tabs UI + copy).Pre.astrois deleted;MarkdownCodeis inline-only;.astro-codefont rules move toshiki-transformers.css. Fences inside authored<TabsPanel>are not wrapped.Deps & tests: Adds
satteri; dropsmdast-util-to-stringandunist-util-visit. Vitest coverage exercises the new plugins under the Node environment (Sätteri native binding).Reviewed by Cursor Bugbot for commit 6faed93. Bugbot is set up for automated code reviews on this repo. Configure here.