Add FrontmatterExtension for parsing document metadata

[dereuromark]

Summary

• Adds FrontmatterExtension for parsing YAML/TOML/JSON frontmatter at document start
• Uses ---format syntax (e.g., ---yaml, ---toml) to distinguish from thematic breaks
• Implemented as a pure extension with no core changes needed
• Supports optional djot attributes: ---yaml {.meta key="value"}

Based on discussion in jgm/djot#35 and the tree-sitter-djot grammar approach.

Usage

$ext = new FrontmatterExtension();
$converter = new DjotConverter();
$converter->addExtension($ext);

$html = $converter->convert($djot);

// Access frontmatter after parsing
if ($ext->hasFrontmatter()) {
    echo $ext->getFormat();  // 'yaml'
    echo $ext->getContent(); // Raw YAML string
}

// Parse with your preferred library
$metadata = $ext->getParsedContent(fn($content, $format) => 
    $format === 'yaml' ? Yaml::parse($content) : null
);

Features

• Format-agnostic: raw content accessible for parsing with any library
• Configurable rendering: hidden (default), HTML comment, or custom callback
• Attribute support: ---python {kernel="myproject" #cell-1}
• getParsedContent() helper for easy integration

Out of scope

• This extension would not allow placing the blocks anywhere but the top.
• It would by design then only allow a single one

Use cases for multiple blocks:

• Jupyter-style notebooks: ---python {kernel="myproject" #cell-1}
• Polyglot documents: mix of ---python, ---sql, ---bash
• Section metadata: ---yaml for each section's config

But that could be its own custom extension if needed.

[codecov]

Codecov Report

❌ Patch coverage is 93.61702% with 6 lines in your changes missing coverage. Please review.
✅ Project coverage is 93.92%. Comparing base (9c563ba) to head (ad7c3c0).
⚠️ Report is 4 commits behind head on master.

Files with missing lines	Patch %	Lines
src/Extension/Frontmatter.php	63.63%	4 Missing ⚠️
src/Extension/FrontmatterExtension.php	97.59%	2 Missing ⚠️

Additional details and impacted files

@@             Coverage Diff              @@
##             master     #122      +/-   ##
============================================
+ Coverage     93.83%   93.92%   +0.08%     
- Complexity     2369     2382      +13     
============================================
  Files            79       81       +2     
  Lines          6261     6303      +42     
============================================
+ Hits           5875     5920      +45     
+ Misses          386      383       -3     

☔ View full report in Codecov by Sentry.
📢 Have feedback on the report? Share it here.

🚀 New features to boost your workflow:

• ❄️ Test Analytics: Detect flaky tests, report on failures, and find test suite problems.
• 📦 JS Bundle Analysis: Save yourself from yourself by tracking and limiting bundle sizes in JS merges.

[Copilot]

Pull request overview

Adds a new Djot extension to recognize and expose document-start frontmatter blocks (YAML/TOML/JSON/etc.) using a ---format opener to avoid clashing with thematic breaks, plus documentation and PHPUnit coverage.

Changes:

• Introduces FrontmatterExtension to parse ---format ... --- blocks at document start and expose raw content/format/attributes.
• Adds a Frontmatter block node type and render controls (hidden by default, HTML comment, or custom callback).
• Adds user-facing docs and a comprehensive test suite for the new extension behavior.

Reviewed changes

Copilot reviewed 4 out of 4 changed files in this pull request and generated 6 comments.

File	Description
src/Extension/FrontmatterExtension.php	Implements the frontmatter block pattern, state storage, and render-time output handling.
src/Extension/Frontmatter.php	Adds a new block node type to represent parsed frontmatter in the AST.
tests/TestCase/Extension/FrontmatterExtensionTest.php	Adds PHPUnit tests for parsing, rendering options, attributes, and helper methods.
docs/extensions/index.md	Documents FrontmatterExtension usage, options, and syntax.

---

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.