Skip to content

Integrate astro-xmdx into withastro/docs#13274

Draft
jp-knj wants to merge 7 commits intowithastro:mainfrom
jp-knj:feat/astrojs-mdx-to-xmdx
Draft

Integrate astro-xmdx into withastro/docs#13274
jp-knj wants to merge 7 commits intowithastro:mainfrom
jp-knj:feat/astrojs-mdx-to-xmdx

Conversation

@jp-knj
Copy link
Copy Markdown
Member

@jp-knj jp-knj commented Feb 17, 2026 •
edited
Loading

Summary

Adds astro-xmdx as a standalone Astro integration to the docs site, replacing @expressive-code/plugin-collapsible-sections with xmdx's built-in Expressive Code support via the Starlight preset.

Changes

  • Adds astro-xmdx@0.0.10-next.8 and xmdx@0.0.9-next.2 as dependencies
  • Configures xmdx() integration in astro.config.ts with starlightPreset and Expressive Code
  • Removes @expressive-code/plugin-collapsible-sections (handled by xmdx)
  • Updates @astrojs/starlight to a prerelease version (@5173976) compatible with xmdx
  • Adds rawContent: true to starlight-llms-txt to avoid compatibility issues with the xmdx compiler
  • Adds vite.ssr.noExternal: ['xmdx'] for SSR compatibility
  • Applies minor MDX formatting fixes

Benchmark

From jp-knj/xmdx#25 (CI, full withastro/docs build):

Command Mean [s] Min [s] Max [s] Relative
@astrojs/mdx 383.694 ± 4.463 378.624 387.032 1.17 ± 0.04
astro-xmdx 328.865 ± 10.096 321.346 340.339 1.00

Notes for reviewers

  • Uses prerelease versions of @astrojs/starlight, astro-xmdx, and xmdx
  • This reduces CPU time spent on MDX compilation by ~76%.
  • it can improve build performance on multi-core machines

Test

  • on dev, quickly check for any layout issues
  • on preview, quickly check for any layout issues

@netlify
Copy link
Copy Markdown

netlify Bot commented Feb 17, 2026 •
edited
Loading

✅ Deploy Preview for astro-docs-2 ready!

Built without sensitive environment variables

Name Link
🔨 Latest commit d70c905
🔍 Latest deploy log https://app.netlify.com/projects/astro-docs-2/deploys/69b4cc114b2ff700085387fa
😎 Deploy Preview https://deploy-preview-13274--astro-docs-2.netlify.app
📱 Preview on mobile
Toggle QR Code...

QR Code

Use your smartphone camera to open QR code link.

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

@github-actions github-actions Bot added the i18n Anything to do with internationalization & translation efforts - ask @YanThomas for help! label Feb 17, 2026
@astrobot-houston
Copy link
Copy Markdown
Contributor

astrobot-houston commented Feb 17, 2026 •
edited
Loading

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

File Note
es/recipes/making-toolbar-apps.mdx Localization changed, will be marked as complete.
ja/guides/testing.mdx Localization changed, will be marked as complete.
ru/guides/testing.mdx Localization changed, will be marked as complete.
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.

@jp-knj jp-knj force-pushed the feat/astrojs-mdx-to-xmdx branch 11 times, most recently from 5f6706b to 45771e8 Compare February 22, 2026 07:07
@jp-knj jp-knj force-pushed the feat/astrojs-mdx-to-xmdx branch 2 times, most recently from 9c44744 to e56a05b Compare March 6, 2026 13:12
@jp-knj jp-knj force-pushed the feat/astrojs-mdx-to-xmdx branch 8 times, most recently from 1d5dbeb to 2b7a116 Compare March 9, 2026 15:27
jp-knj
jp-knj commented Mar 9, 2026
View reviewed changes
Comment thread src/content/docs/es/recipes/making-toolbar-apps.mdx
:::note[Usando rutas relativas en el entrypoint]
El `entrypoint` es la ruta al archivo de tu aplicación de barra de herramientas, **relativo a la raíz de tu proyecto de Astro existente**, no al directorio de integración (`my-toolbar-app/`) por sí mismo.

:::
Copy link
Copy Markdown
Member Author

@jp-knj jp-knj Mar 9, 2026

Choose a reason for hiding this comment

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

if no closing tag, it has some errors.

@jp-knj jp-knj force-pushed the feat/astrojs-mdx-to-xmdx branch from 2b7a116 to 698c980 Compare March 9, 2026 15:34
@jp-knj jp-knj force-pushed the feat/astrojs-mdx-to-xmdx branch from 698c980 to f36c2e1 Compare March 9, 2026 15:37
jp-knj
jp-knj commented Mar 10, 2026
View reviewed changes
Comment thread src/content/docs/ja/guides/testing.mdx
after(browser => browser.end());
});
```
2. 新しいフォルダ`src/test/`を作成し、以下のテストファイルを追加します:
Copy link
Copy Markdown
Member Author

@jp-knj jp-knj Mar 10, 2026

Choose a reason for hiding this comment

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

mixed indentation and whitespace here are fragile and tends to break parsing

@jp-knj jp-knj changed the title [WIP] Introduce xmdx Integrate astro-xmdx into withastro/docs Mar 10, 2026
@jp-knj jp-knj mentioned this pull request Mar 10, 2026
Closed
1 task
@jp-knj jp-knj force-pushed the feat/astrojs-mdx-to-xmdx branch from 307feb7 to b60d68e Compare March 11, 2026 09:14
@jp-knj jp-knj force-pushed the feat/astrojs-mdx-to-xmdx branch from 08dbb09 to 9994fcb Compare March 11, 2026 09:33
@jp-knj jp-knj marked this pull request as ready for review March 11, 2026 10:27
@delucis
Copy link
Copy Markdown
Member

delucis commented Mar 11, 2026

Hey @jp-knj! I saw you marked this PR as “ready for review”. Amazing work getting everything working 👏

Just as a general thought: I don’t think it’s likely that we’ll merge this because it’s important for us to be using our official packages (@astrojs/mdx in this case), so that we have experience of how they behave, what we can improve etc. I had assumed you were just using this PR as a way to test things against the CI and confirm your package was working as expected.

It might be best to try and work out with other maintainers whether we have a way to support faster MDX processing more generally for Astro users.

@jp-knj
Copy link
Copy Markdown
Member Author

jp-knj commented Mar 12, 2026

That's right. I'll go ahead and close this PR. Thanks!

@jp-knj jp-knj closed this Mar 12, 2026
@delucis
Copy link
Copy Markdown
Member

delucis commented Mar 12, 2026

Thanks @jp-knj! And again, super exciting to see this working 🥳

@jp-knj jp-knj reopened this Mar 13, 2026
@jp-knj
fix: resolve merge conflicts and update deps
d70c905 
- Merge upstream/main
- Update @astrojs/starlight to 0.38.0
- Add @expressive-code/plugin-collapsible-sections
- Update xmdx to 0.0.9-next.3
@jp-knj jp-knj marked this pull request as draft March 14, 2026 03:20
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Reviewers

No reviews

Assignees

No one assigned

Labels

🚨 action i18n Anything to do with internationalization & translation efforts - ask @YanThomas for help!

Projects

None yet

Milestone

No milestone

Development

Successfully merging this pull request may close these issues.

3 participants

@jp-knj @astrobot-houston @delucis