feat: docs for pluggable Markdown processors by Princesseuh · Pull Request #13919 · withastro/docs

Princesseuh · 2026-05-21T00:00:43Z

Description (required)

Docs for ~~withastro/astro#16149~~ withastro/astro#16848

netlify · 2026-05-21T00:00:49Z

✅ Deploy Preview for astro-docs-2 ready!

Name	Link
🔨 Latest commit	`03fd7e7`
🔍 Latest deploy log	https://app.netlify.com/projects/astro-docs-2/deploys/6a111a723c7b9a00088566ad
😎 Deploy Preview	https://deploy-preview-13919--astro-docs-2.netlify.app
📱 Preview on mobile	Toggle QR Code... Use your smartphone camera to open QR code link.
🤖 Make changes	Run an agent on this branch

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

astrobot-houston · 2026-05-21T00:01:24Z

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
en/guides/integrations-guide/mdx.mdx	Source changed, localizations will be marked as outdated.
en/guides/markdown-content.mdx	Source changed, localizations will be marked as outdated.
en/guides/migrate-to-astro/index.mdx	Source changed, localizations will be marked as outdated.
en/reference/content-loader-reference.mdx	Source changed, localizations will be marked as outdated.
en/reference/modules/astro-content.mdx	Source changed, localizations will be marked as outdated.
en/reference/programmatic-reference.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.

ArmandPhilippot

Great work, Erika! I left a few comments, mostly nits and two questions where we now show how to do something with @astrojs/markdown-remark but without any equivalent for Sätteri.

And, as far as I can tell, the broken links should be fixed once your core PR is merged!

ArmandPhilippot · 2026-05-22T13:08:11Z

 MDX will extend [your project's existing Markdown configuration](/en/reference/configuration-reference/#markdown-options) by default. To override individual options, you can specify their equivalent in your MDX configuration.

-For example, say you need to disable GitHub-Flavored Markdown and apply a different set of remark plugins for MDX files. You can apply these options like so, with `extendMarkdownConfig` enabled by default:
+For example, say you need to use a different syntax highlighter and disable GitHub-Flavored Markdown for MDX files. You can apply these options like so, with `extendMarkdownConfig` enabled by default:


Either we should remove this:

Suggested change

For example, say you need to use a different syntax highlighter and disable GitHub-Flavored Markdown for MDX files. You can apply these options like so, with `extendMarkdownConfig` enabled by default:

For example, say you need to disable GitHub-Flavored Markdown for MDX files. You can apply these options like so, with `extendMarkdownConfig` enabled by default:

or the example should configure a different syntax highlighter (e.g. Prism for Markdown, Shiki for MDX).

Because, if we set Shiki for Markdown, MDX will also use Shiki and so, we use the same syntax highlighter, right?

ArmandPhilippot · 2026-05-22T13:08:18Z

+You can customize these heading IDs with a [Markdown processor](#choosing-a-markdown-processor) plugin that injects `id` attributes (e.g. `rehype-slug`). Your custom IDs, instead of Astro's defaults, will be reflected in the HTML output and the items returned by `getHeadings()`.

-By default, Astro injects `id` attributes after your rehype plugins have run. If one of your custom rehype plugins needs to access the IDs injected by Astro, you can import and use Astro’s `rehypeHeadingIds` plugin directly. Be sure to add `rehypeHeadingIds` before any plugins that rely on it:
+When using the [remark/rehype processor](#using-remark-and-rehype-plugins), Astro injects `id` attributes after your rehype plugins have run. If one of your custom rehype plugins needs to access the IDs injected by Astro, you can import and use Astro’s `rehypeHeadingIds` plugin directly. Be sure to add `rehypeHeadingIds` before any plugins that rely on it:


So, this is no longer supported with Sätteri? I mean if a user wants to access/manipulate the ids in a custom HAST plugin, is it possible and should we explain how it works with Sâtteri?

It's still possible, yes! The same Astro plugin does exists in the Sätteri pipeline. I'll have to check if it runs in the same order though, I believe right now user's plugins might be running after always.

ArmandPhilippot · 2026-05-22T13:21:06Z

 ### Modifying frontmatter programmatically

-You can add frontmatter properties to all of your Markdown and MDX files by using a [remark or rehype plugin](#markdown-plugins).
+Using the [remark/rehype processor](#using-remark-and-rehype-plugins), you can add frontmatter properties to all of your Markdown and MDX files with a remark or rehype plugin.


Same question as before, does this mean this is no longer supported with Sätteri? Otherwise, it could be helpful to use <Tabs /> to show how to do that with both processors.

Hmm, this is good shout. This one is in fact not supported right now in Sätteri. Sätteri doesn't have a "global data store" thing per file like unified does, but Astro's plugin does rely on that.

Co-authored-by: Armand Philippot <git@armand.philippot.eu>

Princesseuh mentioned this pull request May 21, 2026

feat: A native pipeline for content withastro/astro#16149

Closed

ArmandPhilippot added merge-on-release Don't merge this before the feature is released! (MQ=approved but WAIT for feature release!) 7.0 labels May 21, 2026

ArmandPhilippot added this to the v7 milestone May 21, 2026

ArmandPhilippot reviewed May 22, 2026

View reviewed changes

Princesseuh mentioned this pull request May 23, 2026

feat: add markdown processor abstraction withastro/astro#16848

Open

Princesseuh removed the 7.0 label May 23, 2026

Princesseuh modified the milestones: v7, 6.4 May 23, 2026

Princesseuh changed the base branch from v7 to main May 23, 2026 02:03

github-actions Bot added i18n Anything to do with internationalization & translation efforts - ask @YanThomas for help! 🚨 action labels May 23, 2026

Princesseuh and others added 5 commits May 23, 2026 04:07

feat: docs for pluggable Markdown processors

f294490

Update src/content/docs/en/guides/markdown-content.mdx

9fc3795

Co-authored-by: Armand Philippot <git@armand.philippot.eu>

Update src/content/docs/en/guides/markdown-content.mdx

3fa9a1a

Co-authored-by: Armand Philippot <git@armand.philippot.eu>

Update src/content/docs/en/recipes/reading-time.mdx

0160ad7

Co-authored-by: Armand Philippot <git@armand.philippot.eu>

Update src/content/docs/en/guides/markdown-content.mdx

543fb80

Co-authored-by: Armand Philippot <git@armand.philippot.eu>

Princesseuh force-pushed the feat/markdown-agnostic branch from b13ef9c to 543fb80 Compare May 23, 2026 02:09

Princesseuh added 3 commits May 23, 2026 04:09

Merge branch 'main' into feat/markdown-agnostic

2b01f35

fix: rework for main

a84b870

fix: bring back changes

c1ffee2

Princesseuh commented May 23, 2026

View reviewed changes

Comment thread src/content/docs/en/guides/integrations-guide/mdx.mdx

Apply suggestion from @Princesseuh

03fd7e7

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Uh oh!

feat: docs for pluggable Markdown processors#13919

feat: docs for pluggable Markdown processors#13919
Princesseuh wants to merge 9 commits into
mainfrom
feat/markdown-agnostic

Princesseuh commented May 21, 2026 •

edited

Loading

Uh oh!

netlify Bot commented May 21, 2026 •

edited

Loading

Uh oh!

astrobot-houston commented May 21, 2026 •

edited

Loading

Uh oh!

ArmandPhilippot left a comment

Uh oh!

ArmandPhilippot May 22, 2026

Uh oh!

ArmandPhilippot May 22, 2026

Uh oh!

Princesseuh May 22, 2026

Uh oh!

Uh oh!

ArmandPhilippot May 22, 2026

Uh oh!

Princesseuh May 22, 2026

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

3 participants

	For example, say you need to use a different syntax highlighter and disable GitHub-Flavored Markdown for MDX files. You can apply these options like so, with `extendMarkdownConfig` enabled by default:
	For example, say you need to disable GitHub-Flavored Markdown for MDX files. You can apply these options like so, with `extendMarkdownConfig` enabled by default:

Uh oh!

Conversation

Princesseuh commented May 21, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Description (required)

Uh oh!

netlify Bot commented May 21, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

✅ Deploy Preview for astro-docs-2 ready!

Uh oh!

astrobot-houston commented May 21, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Lunaria Status Overview

Tracked Files

Uh oh!

ArmandPhilippot left a comment

Choose a reason for hiding this comment

Uh oh!

ArmandPhilippot May 22, 2026

Choose a reason for hiding this comment

Uh oh!

ArmandPhilippot May 22, 2026

Choose a reason for hiding this comment

Uh oh!

Princesseuh May 22, 2026

Choose a reason for hiding this comment

Uh oh!

Uh oh!

ArmandPhilippot May 22, 2026

Choose a reason for hiding this comment

Uh oh!

Princesseuh May 22, 2026

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

3 participants

Princesseuh commented May 21, 2026 •

edited

Loading

netlify Bot commented May 21, 2026 •

edited

Loading

astrobot-houston commented May 21, 2026 •

edited

Loading