Add Markdoc preset and example

[HiDeoo]

Description

This PR adds a Markdoc preset and example to Starlight so that users can more easily use or get started with Markdoc in Starlight.

Limitations

There are a few limitations in the current version due to either Markdoc itself or other constraints. They are all documented in the preset itself but I will list the most important ones here:

• icon attributes do not have an explicit set of matches and just accept any string.
• A few components that accept extra props, e.g. all attributes of the <a> tag, don't have the same parity in Markdoc.
  • The associated tags now support a list of well-known attributes that we can improve over time.
• Fenced code blocks do not support markers as Markdoc ignore them, so user would need to use the code tag instead with the meta attribute.

I'll try to see if there are some valid workarounds for these limitations.

There is also an issue that we cannot use the extends field in a markdoc.config.mjs file. Using it lead to an Unable to render [object Object]. No valid renderer was found for this file extension. error.
I'll have to investigate this issue further to see if it's a bug or a real limitation, e.g. maybe not being able to use component in the extends field for some reason.
Opened withastro/astro#11846 to fix this issue.

Testing

We briefly discussed about ensuring some kind of sync between Starlight user components and their tags equivalent in Markdoc. I opted to use type testing as I think it may be one of the easiest approach to this.

We can rely on the amazing ComponentProps type from Astro to extract user components props and TypeScript type-inference on the preset (that only use satisfies to keep the most specific type) to extract Markdoc tags attributes. We can then compare the two types to ensure they are in sync.

At the moment, there are 2 type of type tests:

• We test that all user components have an equivalent Markdoc tag in the Markdoc preset.
• We test that each Markdoc tag have attributes that matches the props of the equivalent user component (we don't test the type of the attributes, only their presence so far. Not sure yet if we should test the type as well as this may add a lot more complexity).

We rely on a few Vitest type testing utilities but we do not run these tests using Vitest as type tests seems a bit fragile when using Vitest workspaces, and also because Vitest would use tsc to run those and this would not play well with Astro components. Instead, the already existing pnpm typecheck command will ensure these tests are valid.

Documentation

Need to think a bit more about this. I think we should at least have documentation on how to use the new Markdoc preset. Not sure yet tho where this documentation should be placed, the "Authoring Content in Markdown" page may not be the best place for this.

I added a new Markdoc documentation section using the same structure used for @astrojs/starlight-tailwind.

• Currently at the bottom of the "Authoring Content in Markdown" guide (not quite sure yet if it's the best place for it)
• I purposefully kept some unrelated formatting changes in the document as it was changed from .md to .mdx and we know how Prettier & MDX can be a bit tricky sometimes so I wanted to make sure nothing would break when the formatter would run.

Remaining tasks

• Wait for Fix component defined in extends not rendered as Markdoc tags/nodes astro#11846 to be merged and released
  • Update packages/markdoc/package.json file peerDependencies to use the new @astrojs/markdoc version
  • Update examples/markdoc/markdoc.config.mjs to use the extends syntax
• Documentation
  • Figure out the best place for it
  • When done with the documentation, update the link to it in packages/markdoc/README.md
• Do we want a GitHub label for this new package
  • If yes, .github/labeler.yml should be updated
• Remove sidebar demo group from examples/markdoc/astro.config.mjs
• Remove the examples/markdoc/src/content/docs/demo/ folder and all its content
• Add a changeset

[changeset-bot]

🦋 Changeset detected

Latest commit: 4bae5e3

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-markdoc	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]

✅ Deploy Preview for astro-starlight ready!

Name	Link
🔨 Latest commit	4bae5e3
🔍 Latest deploy log	https://app.netlify.com/sites/astro-starlight/deploys/66db27a4b898dd0008e8c651
😎 Deploy Preview	https://deploy-preview-2249--astro-starlight.netlify.app
📱 Preview on mobile	Toggle QR Code... Use your smartphone camera to open QR code link.
Lighthouse	1 paths audited Performance: 100 (no change from production) Accessibility: 100 (no change from production) Best Practices: 100 (no change from production) SEO: 92 (no change from production) PWA: - View the detailed breakdown and full score reports

---

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

[delucis]

Thanks for working on this @HiDeoo!

Quick meta question ahead of a more thorough review: do you think this might make more sense as a standalone package Markdoc users need to install? As they will in any case need to add some manual config, the extra friction to npm i @astrojs/starlight-markdoc-preset or whatever the package name is, doesn’t seem too bad and would help keep things separate.

[HiDeoo]

Quick meta question ahead of a more thorough review: do you think this might make more sense as a standalone package Markdoc users need to install? As they will in any case need to add some manual config, the extra friction to npm i @astrojs/starlight-markdoc-preset or whatever the package name is, doesn’t seem too bad and would help keep things separate.

Good question, I remember when we quickly discussed this we mentioned the possibility of having a dedicated package for this.

The current implementation lives in the core package as it was easier to setup everything but I made sure that everything pretty much depends only on @astrojs/starlight/components, even the tests. So it should be easy to move it to a dedicated package if we want to.

• For a new user using the Markdoc example, this would not change anything, just an extra dependency installed automatically.
• For an existing user adding Markdoc manually, they would install @astrojs/markdoc already so adding the extra dependency would not change a lot.
• For an existing user adding Markdoc using astro add, they would need an extra different command to install the package.

I'm personally leaning towards having a dedicated package for this, as I like the separation (just like @astrojs/markdoc being a separate package), but I don't have a super strong opinion on this. I'm happy to do the work if we decide to go this route, should be pretty straightforward.

[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 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 added, will be tracked.
en	guides/pages.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]

Updated the PR with the following changes:

• Move everything to a dedicated @astrojs/starlight-markdoc package
• Add support for well-known HTML attributes to various tags
• Add a new Markdoc documentation section using the same structure used for @astrojs/starlight-tailwind
  • Currently at the bottom of the "Authoring Content in Markdown" guide (not quite sure yet if it's the best place for it)
  • I purposefully kept some unrelated formatting changes in the document as it was changed from .md to .mdx and we know how Prettier & MDX can be a bit tricky sometimes so I wanted to make sure nothing would break when the formatter would run on main.

I also opened a PR on the astro repo to fix the extends issue I mentioned. We would need to wait for that to be merged and released before releasing the new preset (and make sure the peerDependencies version is updated accordingly). Done, the Markdoc example now uses the extends syntax.

[HiDeoo]

Updated the PR to use @astrojs/markdoc version 0.11.4 as the PR I made got released and also updated the example to use the extends syntax.

I also took a bit of time to try the tooling and more specifically the Visual Studio Code Markdoc language extension:

• I first tried the extension without our preset and a basic configuration defining inline a custom tag.
  • I only got validation to work, e.g. "unknown tag" or "unknown attribute" but no auto-completion on tags, attributes, or any other feature.
• I then tried with our preset:
  • All tags are marked as unknown.
  • Not using the extends syntax and going back to the old ...starlightMarkdoc() syntax makes the extension recognize the tags and attributes for validation.
  • Still no auto-completion or any other feature.
  • It looks like the extension does not support the extends field or maybe it requires a change to the extra markdoc.config.json file required by the extension but I was not able to find any documentation on that (we could document it but this feels more like an issue with the extension than with our preset).

Considering all this, I'm undrafting the PR to get more feedback.

[delucis]

LGTM @HiDeoo! Left a couple of tiny details but I don’t have any major feedback. I think once we have #2121 merged, it would be nice to have a MDX / Markdoc tab to show the component syntax probably?

But that’s for the future.

Edit: missed a couple of your questions in the PR comment:

• I think we might as well update labeler.yml to auto tag PRs for the new package 👍
• And yes, needs a changeset. A minor should trigger publishing the first release as v0.1 I think

[HiDeoo]

I think once we have #2121 merged, it would be nice to have a MDX / Markdoc tab to show the component syntax probably?

Definitely, as soon as this PR is released, I will update #2121 to include the MDX and Markdoc syntax. It would still use the same component but with the Markdoc syntax in a new different slot (altho, the preview will still be the MDX one as this wouldn't change anything). I will also need to research a bit about Markdoc common formatting, if they tend to indent nested tags or not, etc. as I'm not familiar with it but we should provide examples in a format that is common to the users.

Thanks for the review 🙌 I'll tackle the remaining points early next week.

[HiDeoo]

Just updated the PR with the discussed changes.

I also took care of the remaining tasks in the PR body, created the new label (not sure if this was required or not but at least it'll have the appropriate color/description) and added a changeset.

[delucis]

Lovely work! Ready for launch 🚀

[delucis]

Updated the Markdoc example to the latest Astro to match the changes in #2287 and still LGTM!