python-frontmatter

python-frontmatter is a lightweight utility for reading and writing structured metadata embedded at the top of text files — the pattern popularized by static site generators like Jekyll, where a post begins with a fenced block of key-value metadata followed by the actual content. The library handles the split between metadata and body, parses the metadata block with a pluggable handler, and exposes both through a simple Post object with dict-like access.

By default it recognizes YAML front matter delimited by ---, but ships with JSON and TOML handlers too, and lets callers write their own BaseHandler subclass for other formats or custom delimiters. It supports loading from filenames, open file objects, or raw text, and can round-trip a parsed post back into a formatted string or file with frontmatter.dumps() and frontmatter.dump().

The project has been maintained by Chris Amico (eyeseast) since 2014 and is widely used as a building block inside static site generators, content pipelines, and note-taking tools that need to separate metadata from prose without pulling in a full CMS or database.

What You Get

• frontmatter.load() / frontmatter.loads() to parse a file, file-like object, or raw text into a Post with .metadata and .content
• frontmatter.parse() for a lower-level call that returns just the metadata dict and content string, without building a Post
• frontmatter.dump() / frontmatter.dumps() to serialize a Post back into delimited text or write it to a file
• Built-in YAMLHandler, JSONHandler, and (when the optional toml package is installed) TOMLHandler, each detecting its own delimiter format automatically
• A Post object with dict-style __getitem__/__setitem__/keys()/values()/get() so metadata reads like a normal dictionary
• frontmatter.check() / frontmatter.checks() to test whether a file or string contains front matter at all before parsing it

Common Use Cases

• Reading Jekyll- or Hugo-style Markdown posts (YAML front matter + Markdown body) in a Python static site generator or build script
• Building custom content pipelines that need to enrich or rewrite metadata (tags, publish dates, slugs) on a batch of text files and write them back out
• Extracting structured metadata from notes or documents in tools like note-taking apps, wikis, or documentation generators
• Round-tripping a folder of Markdown files through a script that adds computed fields (word count, reading time) to the front matter block
• Validating a directory of content files by checking for required metadata keys before publishing

Under The Hood

Architecture The library is a small package (frontmatter/) split into three modules: __init__.py (the public API — parse, load, loads, dump, dumps, and the Post class), default_handlers.py (format detection and parsing), and util.py (text-normalization helpers). Format handling follows a small strategy pattern: a module-level handlers list holds YAMLHandler/JSONHandler/TOMLHandler instances, detect_format() walks the list calling each handler’s detect() regex until one matches, and the rest of the pipeline (split, load, export, format) dispatches through whichever handler was selected or passed explicitly. Post is a thin wrapper carrying content, metadata, and the originating handler, proxying dict-style access to metadata. Because the only shared mutable state is the handlers list, swapping the handler protocol would touch default_handlers.py and user-authored BaseHandler subclasses without disturbing the loader/dumper entry points.

Tech Stack Pure Python 3.10+ with a single runtime dependency, PyYAML, and an optional toml extra for TOML support; built with uv_build rather than setuptools or hatchling. Development dependencies (declared in both [project.optional-dependencies] and [dependency-groups]) are pytest, mypy, types-PyYAML/types-toml, and sphinx for the Read the Docs-hosted documentation. There’s no web framework, database, or CLI involved — this is a standalone text-parsing library, not an application.

Code Quality Tests live in tests/unit_test.py (390 lines) alongside format-specific fixture directories (tests/yaml/, tests/json/, tests/toml/, tests/empty/), plus a test_docs.py that runs the README and module docstrings themselves as doctest suites, keeping the documented examples verifiably correct. mypy.ini enables strict = True for the frontmatter package, the module ships a py.typed marker, and the codebase uses from __future__ import annotations with full type coverage. GitHub Actions runs the test suite on every push. Error handling is minimal but explicit — load()/dump() raise ValueError on unusable input types rather than failing silently.

What Makes It Unique The library’s distinguishing choice is treating front-matter format as pluggable rather than YAML-only: any BaseHandler subclass can define its own delimiter regex plus parse/export logic, and callers can pass a handler instance directly to skip auto-detection. This is a reasonable, well-scoped strategy pattern applied to a common text-processing problem (Jekyll-style front matter) rather than a novel algorithm or architecture — its value comes from being a stable, minimal, single-purpose building block that static site generators and content pipelines can depend on without pulling in a full templating or CMS framework.