sphinx-obsidian-frontmatter

Your Sphinx docs, ready for your second brain.

sphinx-obsidian-frontmatter turns every page your Sphinx markdown build emits into a proper Obsidian note — complete with a YAML frontmatter block for title, author, version, build date, languages, tags, and whatever custom properties your vault cares about. Write your docs once in reStructuredText. Get clean, Obsidian-native markdown out the other end, automatically, every build.

No manual frontmatter. No copy-paste metadata. No drift between what your docs say and what your vault knows.

Why you'll like it

• Zero-touch. Add two lines to conf.py, run sphinx-build -b markdown, done. Every page gets frontmatter, automatically, forever.
• Obsidian-shaped output. Unquoted scalars, flow-style lists (tags: [api, internal]) — frontmatter that looks like a human (or Obsidian) wrote it, not a YAML dumper.
• Your metadata, your rules. Tags, languages, timezone-aware build dates, and an open-ended obsidian_properties dict for anything else your vault's schema needs.
• Safe by default. Bad config — an invalid timezone, a malformed property — fails the build loudly, immediately, instead of shipping silently broken frontmatter.
• Rebuild-friendly. Incremental builds replace stale frontmatter instead of stacking duplicate blocks on top of it.

Quickstart

pip install sphinx-obsidian-frontmatter sphinx-markdown-builder

# conf.py
extensions = [
    "sphinx_markdown_builder",
    "sphinxcontrib.sphinx_obsidian_frontmatter",
]

obsidian_tags = ["docs", "api"]
obsidian_languages = ["python"]
obsidian_timezone = "America/Los_Angeles"
obsidian_properties = {"ecosystem": "acme-widgets"}

sphinx-build -b markdown doc/source doc/build/markdown

Every emitted page now starts with:

---
title: Getting Started
author: Chris Malek
version: 1.2
date: 2026-08-26
language: [python]
tags: [docs, api]
ecosystem: acme-widgets
---

Drop the output straight into your Obsidian vault and it's already tagged, dated, and linked into your metadata system.

Learn more

Full configuration reference, troubleshooting, and the design rationale behind every rendering rule live in the docs: https://sphinx-obsidian-frontmatter.readthedocs.io/en/latest/

Links

• Source
• Bugs
• Documentation