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: d5c4ef5

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