feat(markdown): add support for TOML frontmatter in Markdown files.

[colinbate]

Changes

• Changed the frontmatter parsing in @astrojs/markdown-remark to accept TOML format
• Uses +++ as the delimiters
• Doesn't require configuration
  • If the TOML delimiters are used it will parse as TOML
  • Otherwise defaults to YAML

Testing

Updated the frontmatter.test.js file, adding TOML equivalent tests alongside the existing YAML tests. Worth noting that the TOML test run notably faster, owing to the faster parsing

Docs

This is certainly something that should be documented. It allows you to use TOML based frontmatter, which is particularly useful if migrating from Hugo or another system that preferred TOML and you don't want to convert potentially thousands of files.

Works for content collections, or with standalone markdown files.

/cc @withastro/maintainers-docs for feedback!

[ematipico]

Why would we allow TOML frontmatter in .mdx files but not in .md files? It seems a missed opportunity

[colinbate]

@ematipico Apologies, I didn't mean to imply this was only for MDX files. It works for both.

[sarah11918]

This is certainly something that should be documented.

Yes, yes it should! 😄 But cool feature!

Please make sure to loop me in early on this for any docs work if the feature is accepted! Off the top of my head:

• The Markdown Guidecan also include intro paragraph mentions "can also include frontmatter YAML" and we'd probably update to something like "frontmatter YAML (or TOML)"

• on the same page, we mention that if you are importing Markdown you have access to frontmatter values on the frontmatter object. Is this also true when using TOML? If so, we should similarly have a brief mention here.

• the Migrate from Hugo Guide mentions the difference in the available frontmatter formats will need to be updated. (And, any other "migrate from" where this is also the case!)

• The MDX page seems pretty future-proof, mostly only mentioning "your Markdown frontmatter" instead of YAML explicitly except for again when describing exported properties available on the frontmatter object.

Note that I don't think we need e.g. a new section on "Using TOML for your frontmatter instead." I would simply update wherever we do reference YAML specifically as "the" frontmatter language. As long as the values in frontmatter are used the same way, whether YAML or TOML, there's no need to really call out one language or another.

[colinbate]

Thanks Sarah, yes the values are there on the frontmatter property for imported Markdown.

And I agree that it doesn't need to be called out in a big way. Having it mentioned when frontmatter comes up is fine. I think as long as it surfaces when someone searches the docs for TOML then it will be a win.

[changeset-bot]

🦋 Changeset detected

Latest commit: dd11713

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

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

[ematipico]

The whole team is onboard with the new feature, however we need to have documentation in place.

Once the documentation is there, we can merge it with the other minors

[colinbate]

OK, I'll add the updates to the docs, coordinating with @sarah11918

[sarah11918]

Approving for docs! The docs PR is ready to go for the next release. 🥳

[ematipico]

This looks good to me code-wise. We will update the changeset, and release the feature next week. Thank you @colinbate

[sarah11918]

Suggested change

	Add support for TOML frontmatter in .md and .mdx files
	Uses the standard +++ as a delimiter
	Adds support for TOML frontmatter in `.md` and `.mdx` files
	Astro 5.2 automatically identifies the format of your Markdown and MDX frontmatter based on the delimiter used. With `+++` as a delimiter (instead of the `---` YAML code fence), your frontmatter will automatically be recognized and parsed as [TOML](https://toml.io).
	This is useful for adding existing content files with TOML frontmatter to your project from another framework such as Hugo.
	TOML frontmatter can also be used with [content collections](https://docs.astro.build/guides/content-collections/), and files with different frontmatter languages can live together in the same project.
	No configuration is required to use TOML frontmatter in your content files. Your delimiter will indicate your chosen frontmatter language:
	```md
	+++
	date = 2025-01-30
	title = 'Use TOML frontmatter in Astro!'
	[params]
	author = 'Colin Bate'
	+++
	# Support for TOML frontmatter is here!
	```

OK, just a rough draft suggestion, but for a minor, we can certainly hype the feature!! (Also, I made some assumptions pre-answering questions people might have, and snagged the code example from Hugo's frontmatter example, so adjust for accuracy.)

Something this length/style would totally be appropriate, I think. Feel free to play around with something like this!

[ematipico]

I would change the snippet like this:

[params]
-  author = 'Colin Bate'
+author = 'Colin Bate'

Generally, people don't add spaces or tabs in TOML files. The rest is very good!

[colinbate]

That was a fine description Sarah, thanks. I just tweaked the example a bit.