Repository navigation
feat: add support for Astro 6.4 and Sätteri - #3923
Conversation
🦋 Changeset detectedLatest commit: 76eb2e8 The changes in this PR will be included in the next version bump. This PR includes changesets to release 1 package
Not sure what this means? Click here to learn what changesets are. Click here if you're a maintainer who wants to add another changeset to this PR |
✅ Deploy Preview for astro-starlight ready!
To edit notification comments on pull requests, go to your Netlify project configuration. |
|
Hello! Thank you for opening your first PR to Starlight! ✨ Here’s what will happen next:
|
size-limit report 📦
|
Lunaria Status Overview🌕 This pull request will trigger status changes. Learn moreBy default, every PR changing files present in the Lunaria configuration's You can change this by adding one of the keywords present in the Tracked Files
Warnings reference
|
There was a problem hiding this comment.
Thanks a lot 🙌 This is definitely one impressive first PR 😅
I didn't get the time to go over all the changes yet or play enough with the code, but I'm sharing some initial thoughts and questions.
On a more global level, I'm a bit confused on how to use the new processor with our docs, e.g. if I install @astrojs/markdown-satteri in our docs/ directory, and set markdown: { processor: satteri() }, I get the following error:
❯ nr dev
$ astro dev
17:33:37 [ERROR] [@astrojs/starlight] An unhandled error occurred while running the "astro:config:setup" hook
Vite module runner has been closed.
Location:
/Users/hideo/Temp/starlight/node_modules/.pnpm/vite@7.3.2_@types+node@24.12.4_jiti@2.6.1_lightningcss@1.32.0_yaml@2.8.3/node_modules/vite/dist/node/module-runner.js:1081:26
Stack trace:
at ModuleRunner.getModuleInformation (file:///Users/hideo/Temp/starlight/node_modules/.pnpm/vite@7.3.2_@types+node@24.12.4_jiti@2.6.1_lightningcss@1.32.0_yaml@2.8.3/node_modules/vite/dist/node/module-runner.js:1081:26)
at request (file:///Users/hideo/Temp/starlight/node_modules/.pnpm/vite@7.3.2_@types+node@24.12.4_jiti@2.6.1_lightningcss@1.32.0_yaml@2.8.3/node_modules/vite/dist/node/module-runner.js:1103:94)
at astro:config:setup (/Users/hideo/Temp/starlight/packages/starlight/index.ts:98:73)
at async runHookInternal (file:///Users/hideo/Temp/starlight/node_modules/.pnpm/astro@6.4.2_@types+node@24.12.4_jiti@2.6.1_lightningcss@1.32.0_rollup@4.53.3_yaml@2.8.3/node_modules/astro/dist/integrations/hooks.js:52:5)
at async createContainer (file:///Users/hideo/Temp/starlight/node_modules/.pnpm/astro@6.4.2_@types+node@24.12.4_jiti@2.6.1_lightningcss@1.32.0_rollup@4.53.3_yaml@2.8.3/node_modules/astro/dist/core/dev/container.js:21:14)
[ELIFECYCLE] Command failed with exit code 1.
One last point, if someone configures markdown: { processor: unified() }, or not configure any processor at all, I wonder if the deprecation log could be a bit annoying:
[astro] `markdown.remarkPlugins`, `markdown.rehypePlugins`, and `markdown.remarkRehype` are deprecated. Pass them to `unified({...})` from `@astrojs/markdown-remark` directly instead.
|
Quick status update here, Starlight's tests found an actual issue in Sätteri that I'm fixing here: bruits/satteri#68 |
| function ltrRawPre(value: string): string | null { | ||
| const openTag = value.match(rawPreOpenTag)?.[0]; | ||
| if (!openTag || /\sdir\s*=/.test(openTag)) return null; | ||
| return value.replace(openTag, () => `<pre dir="ltr"${openTag.slice(4)}`); | ||
| } |
There was a problem hiding this comment.
This is something unfortunate I didn't realize, when I did shiki highlighting in Astro for Sätteri, I figured that using toHTML (or whatever it's called) is fine (and much faster), but I didn't realize it meant plugins can't interact with the shiki HAST in other plugins. Something to fix in Astro, or tolerate for now, I guess...
commit: |
|
Thanks to the bug fixes in the latest patch version of Sätteri, we can now properly build the Starlight Docs and also the Astro Docs using Sätteri. Considering this, I re-enabled support for Sätteri, removed the previous Expressive Code disclaimer, and a preview release is now available here. I still want to take a final look at all the recent changes, Edit: forgot to mention, I ran our visual diff checker on all pages and no visual differences were found. |
delucis
left a comment
There was a problem hiding this comment.
Thanks for the awesome work @Princesseuh and @HiDeoo! Left some thoughts, although I will admit I did not read through all the tests 😅
| // For some reason, trying to `await import("./satteri")` in the integration module causes a Vite | ||
| // error about the module runner being closed. This shape works, not sure why! | ||
| export const satteriIntegration = import('./satteri').catch(() => null); |
There was a problem hiding this comment.
Any more information about why this error was happening we could add here?
Also, do we really need to export this, import it in index.ts, only to then pass it into the applyStarlightMarkdownPlugins export from this file?
If we loaded it in the apply function, we could gate loading of the module on if it’s actually needed? i.e.
const satteriIntegration = processor.name === 'satteri' ? await import('./satteri') : null;That might also give us a chance to avoid catching the error which could be silencing something meaningful?
There was a problem hiding this comment.
Done in c9ff3e6 (this PR), seems to work fine even in a project not having @astrojs/markdown-satteri, but I'll let @Princesseuh have the final say as this was part of the initial implementation and not sure if I may be missing any edge cases.
Co-authored-by: delucis <357379+delucis@users.noreply.github.com>
Co-authored-by: delucis <357379+delucis@users.noreply.github.com>
Co-authored-by: delucis <357379+delucis@users.noreply.github.com>
Co-authored-by: delucis <357379+delucis@users.noreply.github.com>
Co-authored-by: delucis <357379+delucis@users.noreply.github.com>
Co-authored-by: delucis <357379+delucis@users.noreply.github.com>
| const satteri = await getSatteriIntegration(processor); | ||
|
|
||
| if (satteri?.isSatteriProcessor(processor)) { |
There was a problem hiding this comment.
We already check we have a Sätteri processor in the getSatteriIntegration() function, so the repeated check here is superfluous (isSatteriProcessor() just checks the name field like we do):
| const satteri = await getSatteriIntegration(processor); | |
| if (satteri?.isSatteriProcessor(processor)) { | |
| const satteri = await getSatteriIntegration(processor); | |
| if (satteri) { |
There was a problem hiding this comment.
Alternatively — and maybe preferably? — we could do this? And refactor the get function to not bother with the check?
| const satteri = await getSatteriIntegration(processor); | |
| if (satteri?.isSatteriProcessor(processor)) { | |
| if (processor.name === 'satteri') { | |
| const satteri = await getSatteriIntegration(processor); |
(Also not sure if it has to be a top-level variable? Normally this method should only be called once, right? So there’s not really an advantage to caching the imported module like that? It just adds a bit of complexity.)
There was a problem hiding this comment.
isSatteriProcessor() (and also isUnifiedProcessor()) are type guards, e.g. without them, TypeScript would complain, for example when trying to assign processor.options.features.directive that is only possible with Sätteri.
No matter what, I ended reverting my commit changing the logic as while testing a bit more, I discovered that this was also crashing with the same error this PR initially hit ("Vite module runner has been closed" and nothing else) but surprisingly when using Sätteri with @astrojs/markdown-satteri installed…
So far, only Erika's syntax seems to work without any crash in all cases. I think a Vite bug was mentioned but I haven't had the time to investigate it further yet.
There was a problem hiding this comment.
I’ve seen the “Vite module runner has been closed” error around a few places now. I think from the initial Vite instance that is spun up for config parsing closing and some things were relying on it? Would be good to chase down as the current version feels fragile. But don’t want to block this PR on that obviously.
This Astro issue with the error also had to do with dynamic imports: withastro/astro#12689
I suspect other user code with dynamic imports could hit the same issue?
delucis
left a comment
There was a problem hiding this comment.
Thanks again everyone for the great work here! 👏
There’s definitely some details it would be nice to clean up eventually, but I think we should get this published to fix the tables bug and let people start playing with Sätteri.
I think the required changes have all been made.
This PR contains the following updates: | Package | Change | [Age](https://docs.renovatebot.com/merge-confidence/) | [Confidence](https://docs.renovatebot.com/merge-confidence/) | |---|---|---|---| | [@astrojs/starlight](https://starlight.astro.build) ([source](https://github.com/withastro/starlight/tree/HEAD/packages/starlight)) | [`0.39.3` → `0.40.0`](https://renovatebot.com/diffs/npm/@astrojs%2fstarlight/0.39.3/0.40.0) |  |  | --- ### Release Notes <details> <summary>withastro/starlight (@​astrojs/starlight)</summary> ### [`v0.40.0`](https://github.com/withastro/starlight/blob/HEAD/packages/starlight/CHANGELOG.md#0400) [Compare Source](https://github.com/withastro/starlight/compare/@astrojs/starlight@0.39.3...@astrojs/starlight@0.40.0) ##### Minor Changes - [#​3923](withastro/starlight#3923) [`edf2e6b`](withastro/starlight@edf2e6b) Thanks [@​Princesseuh](https://github.com/Princesseuh)! - Adds support for Astro 6.4 and the new Sätteri Markdown processor. It is now possible to opt into using [Astro's 6.4 Sätteri Markdown processor](https://astro.build/blog/astro-640/#faster-markdown-builds-with-s%C3%A4tteri) by installing the `@astrojs/markdown-satteri` package and configuring it in your `astro.config.mjs` file: ```js // astro.config.mjs import { defineConfig } from 'astro/config'; import { satteri } from '@​astrojs/markdown-satteri'; export default defineConfig({ markdown: { processor: satteri(), }, }); ```⚠️ **BREAKING CHANGE:** The minimum supported version of Astro is now v6.4.5. Please update Starlight and Astro together: ```sh npx @​astrojs/upgrade ``` *Community Starlight plugins and Astro integrations may also need to be manually updated to work with Sätteri. If you encounter any issues, please reach out to the plugin or integration author to see if it is a known issue or if an updated version is being worked on.* ##### Patch Changes - [#​3923](withastro/starlight#3923) [`edf2e6b`](withastro/starlight@edf2e6b) Thanks [@​Princesseuh](https://github.com/Princesseuh)! - Updates Expressive Code to version 0.43.1. </details> --- ### Configuration 📅 **Schedule**: (UTC) - Branch creation - At any time (no schedule defined) - Automerge - At any time (no schedule defined) 🚦 **Automerge**: Disabled by config. Please merge this manually once you are satisfied. ♻ **Rebasing**: Whenever PR becomes conflicted, or you tick the rebase/retry checkbox. 🔕 **Ignore**: Close this PR and you won't be reminded about this update again. --- - [ ] <!-- rebase-check -->If you want to rebase/retry this PR, check this box --- This PR has been generated by [Mend Renovate](https://github.com/renovatebot/renovate). <!--renovate-debug:eyJjcmVhdGVkSW5WZXIiOiI0My4yMTQuNSIsInVwZGF0ZWRJblZlciI6IjQzLjIxNC41IiwidGFyZ2V0QnJhbmNoIjoibWFpbiIsImxhYmVscyI6W119-->

Description
This PR adds support for Astro 6.4 and the Sätteri processor introduced in that version. It does so by checking what (if any)
markdown.processoris set, and adding plugins accordingly to that.Versions earlier than 6.4 are also still supported, when
markdown.processorisn't present, Starlight pushes plugins to the now deprecated remarkPlugins / rehypePlugins options instead.This PR does not remove the hard dependency on
@astrojs/markdown-remark, it would be possible to with similar patterns as the ones done for Sätteri, but I figured that it wasn't up to me to decide that.