Skip to content

feat: add support for Astro 6.4 and Sätteri - #3923

Merged
delucis merged 35 commits into
mainfrom
feat/astro-640
Jun 9, 2026
Merged

delucis merged 35 commits into
mainfrom
feat/astro-640

Conversation

@Princesseuh

@Princesseuh Princesseuh commented May 27, 2026 •

Copy link
Copy Markdown
Member

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.processor is set, and adding plugins accordingly to that.

Versions earlier than 6.4 are also still supported, when markdown.processor isn'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.

@changeset-bot

changeset-bot Bot commented May 27, 2026 •

Copy link
Copy Markdown

🦋 Changeset detected

Latest commit: 76eb2e8

The changes in this PR will be included in the next version bump.

This PR includes changesets to release 1 package
Name Type
@astrojs/starlight Minor

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

@netlify

netlify Bot commented May 27, 2026 •

Copy link
Copy Markdown

✅ Deploy Preview for astro-starlight ready!

Name Link
🔨 Latest commit 76eb2e8
🔍 Latest deploy log https://app.netlify.com/projects/astro-starlight/deploys/6a283d5249d62d00086f01fd
😎 Deploy Preview https://deploy-preview-3923--astro-starlight.netlify.app
📱 Preview on mobile
Toggle QR Code...

QR Code

Use your smartphone camera to open QR code link.
Lighthouse
Lighthouse
1 paths audited
Performance: 100 (no change from production)
Accessibility: 100 (no change from production)
Best Practices: 100 (no change from production)
SEO: 100 (no change from production)
PWA: -
View the detailed breakdown and full score reports
🤖 Make changes Run an agent on this branch

To edit notification comments on pull requests, go to your Netlify project configuration.

@astrobot-houston

Copy link
Copy Markdown
Contributor

Hello! Thank you for opening your first PR to Starlight! ✨

Here’s what will happen next:

  1. Our GitHub bots will run to check your changes.
    If they spot any issues you will see some error messages on this PR.
    Don’t hesitate to ask any questions if you’re not sure what these mean!

  2. In a few minutes, you’ll be able to see a preview of your changes on Netlify 🤩

  3. One or more of our maintainers will take a look and may ask you to make changes.
    We try to be responsive, but don’t worry if this takes a few days.

@github-actions github-actions Bot added the 🌟 core Changes to Starlight’s main package label May 27, 2026
@astrobot-houston

astrobot-houston commented May 28, 2026 •

Copy link
Copy Markdown
Contributor

size-limit report 📦

Path Size
/index.html 5.61 KB (+0.02% 🔺)
/_astro/*.js 26.06 KB (0%)
/_astro/*.css 16.12 KB (0%)

Comment thread packages/starlight/package.json Resolved
@github-actions github-actions Bot added the 📚 docs Documentation website changes label Jun 1, 2026
@Princesseuh
Princesseuh marked this pull request as ready for review June 1, 2026 11:38
@astrobot-houston

astrobot-houston commented Jun 1, 2026 •

Copy link
Copy Markdown
Contributor

Lunaria Status Overview

🌕 This pull request will trigger status changes.

Learn more

By default, every PR changing files present in the Lunaria configuration's files property will be considered and trigger status changes accordingly.

You can change this by adding one of the keywords present in the ignoreKeywords property in your Lunaria configuration file in the PR's title (ignoring all files) or by including a tracker directive in the merged commit's description.

Tracked Files

Locale File Note
en guides/authoring-content.mdx Source changed, localizations will be marked as outdated.
Warnings reference
Icon Description
🔄️ The source for this localization has been updated since the creation of this pull request, make sure all changes in the source have been applied.

HiDeoo
HiDeoo previously requested changes Jun 1, 2026

@HiDeoo HiDeoo left a comment •

Copy link
Copy Markdown
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

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.

Comment thread packages/starlight/index.ts Resolved
Comment thread .changeset/satteri-support.md Resolved
@Princesseuh
Princesseuh marked this pull request as draft June 1, 2026 23:46
@Princesseuh

Copy link
Copy Markdown
Member Author

Quick status update here, Starlight's tests found an actual issue in Sätteri that I'm fixing here: bruits/satteri#68

Comment on lines +191 to +195
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)}`);
}

Copy link
Copy Markdown
Member Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

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...

@Princesseuh
Princesseuh marked this pull request as ready for review June 3, 2026 13:30
@Princesseuh
Princesseuh requested a review from HiDeoo June 3, 2026 14:26
Comment thread packages/starlight/package.json Resolved
@HiDeoo HiDeoo added the pr-preview Trigger a preview release for this PR using pkg.pr.new label Jun 9, 2026
@github-actions github-actions Bot removed the pr-preview Trigger a preview release for this PR using pkg.pr.new label Jun 9, 2026
@pkg-pr-new

pkg-pr-new Bot commented Jun 9, 2026

Copy link
Copy Markdown
pnpm add https://pkg.pr.new/withastro/starlight/@astrojs/starlight@3923

commit: 357019f

@HiDeoo

HiDeoo commented Jun 9, 2026 •

Copy link
Copy Markdown
Member

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, make a tiny patch to Expressive Code (done in expressive-code/expressive-code#449), but I think we are very close to have a PR ready to be merged. Feel free to test the preview release and/or review the PR in the meantime.

Edit: forgot to mention, I ran our visual diff checker on all pages and no visual differences were found.

@delucis delucis left a comment

Copy link
Copy Markdown
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Thanks for the awesome work @Princesseuh and @HiDeoo! Left some thoughts, although I will admit I did not read through all the tests 😅

Comment thread .changeset/satteri-support.md Resolved
Comment thread docs/package.json Resolved
Comment thread pnpm-workspace.yaml Resolved
Comment on lines +7 to +9
// 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);

Copy link
Copy Markdown
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

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?

@HiDeoo HiDeoo Jun 9, 2026 •

Copy link
Copy Markdown
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

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.

HiDeoo and others added 6 commits June 9, 2026 15:01
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>
Comment on lines +21 to +23
const satteri = await getSatteriIntegration(processor);

if (satteri?.isSatteriProcessor(processor)) {

@delucis delucis Jun 9, 2026 •

Copy link
Copy Markdown
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

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):

Suggested change
const satteri = await getSatteriIntegration(processor);
if (satteri?.isSatteriProcessor(processor)) {
const satteri = await getSatteriIntegration(processor);
if (satteri) {

Copy link
Copy Markdown
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Alternatively — and maybe preferably? — we could do this? And refactor the get function to not bother with the check?

Suggested change
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.)

Copy link
Copy Markdown
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

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.

@delucis delucis Jun 9, 2026 •

Copy link
Copy Markdown
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

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 delucis left a comment

Copy link
Copy Markdown
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

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.

@delucis
delucis dismissed HiDeoo’s stale review June 9, 2026 17:25

I think the required changes have all been made.

@delucis
delucis merged commit edf2e6b into main Jun 9, 2026
17 checks passed
@delucis
delucis deleted the feat/astro-640 branch June 9, 2026 17:26
@astrobot-houston astrobot-houston mentioned this pull request Jun 9, 2026
ArmandPhilippot added a commit to ArmandPhilippot/starlight that referenced this pull request Jun 10, 2026
dadezzz pushed a commit to dadezzz/university_notes that referenced this pull request Jun 14, 2026
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) | ![age](https://developer.mend.io/api/mc/badges/age/npm/@astrojs%2fstarlight/0.40.0?slim=true) | ![confidence](https://developer.mend.io/api/mc/badges/confidence/npm/@astrojs%2fstarlight/0.39.3/0.40.0?slim=true) |

---

### Release Notes

<details>
<summary>withastro/starlight (@&#8203;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

- [#&#8203;3923](withastro/starlight#3923) [`edf2e6b`](withastro/starlight@edf2e6b) Thanks [@&#8203;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 '@&#8203;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 @&#8203;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

- [#&#8203;3923](withastro/starlight#3923) [`edf2e6b`](withastro/starlight@edf2e6b) Thanks [@&#8203;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-->
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

🌟 core Changes to Starlight’s main package 📚 docs Documentation website changes

Projects

None yet

Development

Successfully merging this pull request may close these issues.

Tables not being rendered anymore

6 participants