Add a reference for Markdown processor packages.

[ArmandPhilippot]

Context: Currently, we have no docs for @astrojs/markdown-remark and @astrojs/markdown-satteri. When we'll remove the deprecated Markdown options, we might want this to live elsewhere. Some helpers are useful for integrations (e.g. Starlight use some of them or use less convenient types).

Description (required)

• Adds a reference page for @astrojs/markdown-remark:
  • I think it makes more sense to provide the options directly under unified(). This allows us to show defaults. So, I removed UnifiedProcessorOptions from the type list.
  • I didn't include UnifiedResolvedOptions. It doesn't seem helpful for users.
  • It seems that unified is always written in lowercase.
• Adds a reference page for @astrojs/markdown-satteri:
  • I think it makes more sense to provide the options directly under satteri(). This allows us to show defaults. So, I removed SatteriProcessorOptions from the type list.
  • I didn't include SatteriResolvedOptions in the end. It seems rather internal?
  • Not sure there is a use case for the SatteriFeatures? So, I put the features directly under the satteri() options.
• Adds them both to the sidebar.
• Adds @astrojs/markdown-remark and @astrojs/markdown-satteri to the content collection config to be able to use <Since />.
• Updates a few links and adds some <ReadMore /> in the Markdown and MDX guides.
• Rewords the recma plugins sections in the MDX guide:
  • reduces repetition by replacing the deprecated recmaPlugins description (we had about the same description in 3 places...)
  • rewords "using recma plugins" to callout earlier this is only available with unified, and give a link to the reference

I took some liberty with a few types:

• Features renamed to SatteriFeatures (they are identical) and so adding a link to Sätteri docs on them might be less confusing.
• Root to MdastRoot/HastRoot with an external link
• I didn't include the deprecated properties in the AstroMarkdownOptions type. Since this wasn't documented yet, I don't think we should show them.

I didn't include some exports that seemed "for Astro-use only" to me:

• rehypeShiki: but I can see some people use it (e.g. in an unexepected next.config.ts file)
• I couldn't find any evidence of external use for the others: satteriCollectHastText, satteriCollectImagesPlugin, satteriCreateHighlightFn, satteriHighlightPlugin, satteriImageMarkerPlugin, extractFrontmatter, isFrontmatterValid, markdownConfigDefaults, parseFrontmatter, rehypePrism, remarkCollectImages, syntaxHighlightDefaults, Node (re-export from unist), ParseFrontmatterOptions, ParseFrontmatterResult

Open questions:

• ShikiConfig:
  • The options are kinda documented in the configuration reference, but written docs instead of a code block seems better (we own the type).
  • Now, maybe we should moved this to the config reference and the ShikiConfig type is not really useful by itself...
  • It seems some people use it, but from a different entrypoint (e.g. an Astro theme)
• The references location is subject to debate:
  • I hesitated between the Reference (kinda similar to the virtual modules, astro/hono, and astro/zod) and Ecosystem (kinda similar to @astrojs/mdx) tabs.
  • Since this is written solely as a reference and this is tied to a core feature, I chose the Reference tab.

If you want to double check the `Since`, click here to expand the list.

• For @astrojs/markdown-remark:
  • Since Improve markdown rendering performance astro#8532 (@astrojs/markdown-remark@3.2.0): createMarkdownProcessor()
  • Since feat: add markdown processor abstraction astro#16848 (@astrojs/markdown-remark@7.2.0): isUnifiedProcessor(), unified(), AstroMarkdownOptions, MarkdownHeading, MarkdownRenderOptions, MarkdownRenderResult, MarkdownRenderer, RehypePlugin, RehypePlugins, RemarkPlugin, RemarkPlugins, RemarkRehype, ShikiConfig, Smartypants, UnifiedProcessorOptions, and UnifiedResolvedOptions
  • Since the same PR as above: MarkdownProcessor and SyntaxHighlightConfig. If I got the history right... This was imported, but never exported before.
  • Since MD/MDX collect headings refactor astro#5654 (@astrojs/markdown-remark@1.2.0): rehypeHeadingIds()
• For @astrojs/markdown-satteri:
  • Since feat(satteri): Use the Sätteri databag for data astro#17129 (@astrojs/markdown-satteri@0.3.1): SatteriAstroData
  • The SatteriFeatures type exists since fix(markdown-satteri): clarify smartPunctuation default astro#17314 (@astrojs/markdown-satteri@0.3.8) but this was just to fix an issue with defaults. So, I added no <Since /> to options.features which exists since feat: add markdown processor abstraction astro#16848 (first release).

References

• Closes Expose @astrojs/markdown-remark as a public API roadmap#1094 (I guess)

[astrobot-houston]

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 tracking.ignoredKeywords 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
guides/integrations-guide/mdx.mdx	Source changed, localizations will be marked as outdated.
guides/markdown-content.mdx	Source changed, localizations will be marked as outdated.
reference/markdown-processors/satteri.mdx	Localization added, will be marked as complete.
reference/markdown-processors/unified.mdx	Localization added, will be marked as complete.
nav/en.ts	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.

[github-actions]

Preview deployment

✅ Deployment complete!

• Latest commit: a281f41
• Preview: https://armand-markdown-processors-reference.previews.docs.astro.build
• Workflow run: View logs

[Princesseuh]

Looks good to me! Bit worrying all the things we export from the Remark processor, but so be it

[ArmandPhilippot]

Well, at least not everything is documented. We can always clean up what sounds internal if there is another way without making this a breaking change! But, yes, there are a lot of things! 😅

Thanks for the review! 💜