sour 0.1.0

A tool for dynamically generating markdown files using references to commands.

Sour 🥒

Sour is a tool for dynamically generating and maintaining markdown files using references to commands and external sources.

🤖 Why Sour?

We are entering the Agentic Era.

In this new paradigm, documentation is no longer just for humans, it's the primary interface for AI Agents. In addition to the existing set of README.mds you have in your codebase, you now need files like AGENTS.md, CLAUDE.md, and GitHub's instruction files, all critical for guiding autonomous agents.

The quality of an agent's output can degrade significantly if there is outdated or false context in your documentation.

Sour solves this by allowing you to generate your documentation from the source of truth. Instead of copy-pasting output, you define how to generate it, ensuring your docs are always 100% accurate.

🏗️ Why not Quarto?

DRY (Don't Repeat Yourself): Quarto is fantastic, but often relies on templates which can introduce duplication. Sour is designed to inject truth directly into your existing markdown files without the need for a complex build chain or intermediate template files.

Simplicity: Quarto is a large, powerful ecosystem. Sour is a small, sharp tool designed specifically for maintaining context for Agents. It does one thing and does it well.

🔒 Safety First

No Arbitrary Execution: Unlike tools that allow running arbitrary bash commands in your documentation (an agentic security nightmare), Sour relies on typed, checked Extensions.

Secure by Design: You define exactly what code can run via extensions. This prevents agents or malicious actors from using your documentation build system as a privilege escalation vector.

✨ Extensions

Sour is designed around Extensions. It comes with powerful built-ins, but you can easily write your own in Python.

🌳 Tree Extension

Automatically visualize your directory structure. It's smart enough to pull descriptions from nested README.md files to annotate your tree.

<!-- docs TREE path="." depth=2 dirs_only=true -->

\```
.
├── examples
│   └── nested # A nested directory for testing tree descriptions
├── src
│   └── sour
└── tests
    └── __pycache__
\```

<!-- /docs -->

🤖 Just Extension

Embed recipes from your justfile directly into your docs. Perfect for "Quick Start" sections.

<!-- docs JUST recipe="test" -->

Run all tests

\```bash
just test
\```

<!-- /docs -->

🔌 Extensible

Add your own extensions by defining a Python function.

# scripts/extensions.py
from sour import register_extension

@register_extension("HELLO")
def hello(content, options, file_path):
    name = options.get("name", "World")
    return f"Hello {name}!"

Usage:

<!-- docs HELLO name="Sour" -->

Hello Sour!

<!-- /docs -->

📈 Star History