LoginSign Up
← Back to all sparks
F

frontmatter

INFRA · APIS
Velocity0.0

Parse Front Matter from Documents

github.com/posit-dev/frontmatter ↗

A small R parser quietly becoming format-agnostic about front matter.

parsingyamltomlr-packagedeveloper-tools
◆Current state
frontmatter extracts and writes YAML or TOML front matter from text documents, with a C++ parser and pluggable YAML and TOML backends. Three releases across six months have taken it from read-only parsing to full roundtrip and then to inferring format automatically. Its scope is deliberately narrow: locating and delimiting the metadata block, and delegating the actual parsing to other packages.
◆Where it's heading
Each release widens the set of files it recognises without widening what it claims to do — standard YAML and TOML fences first, then comment-wrapped R and Python variants and PEP 723 inline script metadata, then shebang-prefixed scripts. The complementary thread is preserving what it found: format and fence type are attached as attributes so a document can be rewritten in the style it arrived in. The remaining rough edge is acknowledged in the notes, since comments and formatting inside the front matter do not survive a roundtrip.
◆Prediction
Expect further delimiter styles as they appear in the wild, and likely work on making the roundtrip preserve comments and formatting, which the package currently flags as imperfect.

◆Recent moves

  1. 1mo ago

    Delimiter inferred automatically, and shebang lines supported

    Writing now infers the delimiter rather than requiring it: front matter that came from this package keeps its original fence style, otherwise the file extension decides and YAML is the fallback. Separately, files beginning with a shebang are handled, with comment-wrapped and PEP 723 front matter recognised immediately after it. Executable scripts are exactly where front matter is most likely to sit behind a shebang, so this closes an obvious gap.

    View source ↗
  2. 6mo ago

    Writing support completes the parse-and-rewrite roundtrip

    Adds format_front_matter() and write_front_matter() as inverses of the existing parsers, covering every supported delimiter style, and attaches format and fence_type as attributes so the original style can be preserved on rewrite. The notes are candid that the roundtrip is imperfect, since comments and formatting inside the block may be lost. Turning a reader into a reader-writer is what makes the package usable for tooling that edits documents rather than only inspecting them.

    View source ↗
  3. 7mo ago

    First release: multi-format front matter parsing in C++

    The initial CRAN release, reading YAML and TOML front matter across standard fences, comment-wrapped R and Python styles, and PEP 723 inline script metadata, with fast C++ parsing and graceful handling of incomplete blocks. Parsing is delegated to yaml12 and tomledit by default but accepts custom parsers. The separation between locating front matter and interpreting it is the design decision the later releases build on.

    View source ↗