python-frontmatter

Handlers define how different metadata formats (like YAML, JSON, or TOML) are parsed and serialized. You can implement custom logic by subclassing frontmatter.default_handlers.BaseHandler.

Built-in handlers include:

• frontmatter.default_handlers.YAMLHandler
• frontmatter.default_handlers.JSONHandler
• frontmatter.default_handlers.TOMLHandler

You can install python-frontmatter using pip or uv.

# with pip
pip install python-frontmatter

# or uv
uv add python-frontmatter

For local development using uv, use:

uv sync

Use frontmatter.load() to load a post from a filename or a file-like object. Use frontmatter.loads() to load from a raw string.

If your file contains a Byte-Order Mark (BOM), it is recommended to use the utf-8-sig encoding when opening the file to strip it automatically.

import frontmatter

# Load from a filename
post = frontmatter.load('tests/yaml/hello-world.txt')

# Load from a file-like object
with open('tests/yaml/hello-world.txt') as f:
    post = frontmatter.load(f)

# Load from text string
post = frontmatter.loads(text_string)

# Handling files with BOM
with open('tests/yaml/hello-world.txt', encoding="utf-8-sig") as f:
    post = frontmatter.load(f)

To convert a post object back into a string with front matter, use frontmatter.dumps(). To write a post object directly to a file-like object, use frontmatter.dump().

import frontmatter
from io import StringIO

# Convert post to a string
output_string = frontmatter.dumps(post)

# Write post to a file-like object
f = StringIO()
frontmatter.dump(post, f)
print(f.getvalue())

When a post is loaded, you can access the body text via post.content or by printing the object directly.

Metadata is stored in a dictionary accessible via post.metadata. Additionally, metadata keys are proxied directly onto the post object, allowing you to access them using dictionary-style key access (e.g., post['key']).

import frontmatter

post = frontmatter.load('tests/yaml/hello-world.txt')

# Access content
print(post.content)

# Access metadata via proxy
print(post['title'])

# Access metadata dictionary directly
print(post.metadata)

If you only need the metadata and the content without the full Post object wrapper, use frontmatter.parse(). This returns a tuple containing the metadata dictionary and the content string.

import frontmatter

with open('tests/yaml/hello-world.txt') as f:
    metadata, content = frontmatter.parse(f.read())

print(metadata['title'])

To save a Post object back to a format containing frontmatter, use:

• frontmatter.dump(post, file): Writes the Post object's metadata and content to a file-like object.
• frontmatter.dumps(post): Returns the Post object's metadata and content as a formatted string.

Use the following functions to extract frontmatter and content from Markdown or other text files:

• frontmatter.load(file): Reads a file-like object and returns a Post object.
• frontmatter.loads(string): Parses a string containing frontmatter and content, returning a Post object.
• frontmatter.parse(file): Parses a file-like object, returning a tuple of (metadata, content).
• frontmatter.check(file): Checks if a file contains valid frontmatter.
• frontmatter.checks(file): Performs multiple validation checks on a file's frontmatter.

The frontmatter.Post class represents a document containing both metadata (frontmatter) and the body content.

It supports dictionary-like access for metadata via:

• __getitem__: Access metadata values using post['key'].
• __setitem__: Set metadata values using post['key'] = value.
• __delitem__: Remove metadata keys using del post['key'].