Metadata-Version: 2.4
Name: sphinx-obsidian-frontmatter
Version: 0.1.1
Summary: A sphinx extension that adds custom obsidian frontmatter yaml when using a markdown output formatter
Author-email: Caltech IMSS ADS <imss-ads-staff@caltech.edu>
Maintainer-email: Chris Malek <cmalek@caltech.edu>
Project-URL: Respository, https://github.com/caltechads/sphinx-obsidian-frontmatter
Project-URL: Documentation, https://sphinx-obsidian-frontmatter.readthedocs.io/en/latest/
Classifier: Development Status :: 3 - Alpha
Classifier: Environment :: Console
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: BSD License
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Topic :: Documentation
Classifier: Topic :: Documentation :: Sphinx
Classifier: Topic :: Utilities
Requires-Python: >=3.11
Description-Content-Type: text/markdown
License-File: LICENSE.txt
Requires-Dist: pbr>=7.0.3
Requires-Dist: sphinx-markdown-builder>=0.6.11
Dynamic: license-file

# 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

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

```python
# 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"}
```

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

Every emitted page now starts with:

```yaml
---
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](https://github.com/caltechads/sphinx-obsidian-frontmatter)
- [Bugs](https://github.com/caltechads/sphinx-obsidian-frontmatter/issues)
- [Documentation](https://sphinx-obsidian-frontmatter.readthedocs.io/en/latest/)
