Skip to main content

rockgarden

A Python static site generator that builds sites from Markdown content. Point it at a directory of Markdown files and get a navigable HTML site: no config required.

Rockgarden supports Obsidian vaults out of the box — wiki-links, embeds, and callouts all work without changing how you write.

Philosophy

Progressive customization. Start with zero config and add complexity only when you need it:

  • Zero config: Point at a folder, get a site
  • Convention: Drop CSS in _styles/, templates in _templates/
  • Configuration: Define collections, navigation, themes in rockgarden.toml
  • Full control: Custom templates, build hooks, data pipelines

The goal is to scale from a personal wiki to a full-featured site without switching tools.

Installation

With uv (recommended):

uv tool install rockgarden

Or with pip:

pip install rockgarden

Quick Start

rockgarden build     # build your site
rockgarden serve     # preview locally

Features

Navigation & discovery:

  • Auto-generated sidebar, breadcrumbs, folder index pages
  • Per-page table of contents
  • Backlinks
  • Client-side full-text search
  • Tag display and tag index pages (/tags/<tag>/)
  • Sitemap generation
  • Broken link detection with visual indication

Customization:

  • Built-in theme with dark/light mode
  • Template overrides via _templates/
  • Layout system with named Jinja2 blocks
  • Custom CSS (_styles/) and JS (_scripts/) auto-injected
  • Theme export for full customization (rockgarden theme export)

Obsidian support:

  • Wiki-links ([[page]], [[page|text]], [[page#section]])
  • Note transclusions (![[note]])
  • Media embeds (images, audio, video, PDF)
  • Callouts (all Obsidian callout types)

Collections:

  • Named content subsets scoped by directory
  • Load data from YAML, JSON, and TOML files
  • Pydantic model validation via _models/
  • Per-collection templates, URL patterns, and page generation
  • Collection entries available in all templates

Build pipeline:

  • Build hooks (pre_build, post_collect, post_build)
  • Content exported to .rockgarden/content.json for hook scripts
  • Base path prefix for subdirectory deploys
  • SEO meta tags from frontmatter (description, Open Graph)

Other:

  • Clean URLs (/page/ instead of /page.html)
  • Accessibility (skip links, ARIA landmarks, focus styles)

CLI Commands

rockgarden build           # build your site
rockgarden serve           # local dev server
rockgarden init            # initialize a new project
rockgarden theme export    # export theme for customization
rockgarden icons update    # download Lucide icons for local override

Configuration

Optional. Create rockgarden.toml to customize:

[site]
title = "My Site"
source = "content"
output = "_site"

[nav]
sort = "files-first"

[theme]
name = "default"

[[collections]]
name = "speakers"
source = "speakers"
template = "speaker.html"
url_pattern = "/speakers/{slug}/"

[hooks]
post_build = ["echo 'Build complete'"]

Development

Requires just and uv.

just install   # install dependencies
just test      # run tests
just check     # lint and format check
just format    # auto-fix lint and formatting
just ci        # lint + tests (run before submitting)
just build     # build the demo site
just serve     # serve output directory
just css       # compile Tailwind CSS

Requirements

Python 3.13+

Acknowledgements

Rockgarden was inspired by Quartz, a static site generator for Obsidian vaults. Check it out as it might be more appropriate for your use case. When I found myself increasingly customizing my installation I decided to start building my own implementation, with the features I always wanted in a static site generator.

Contributing

Contributions may be welcome if they fit the vision of this project. Please open an issue before submitting PRs. See CONTRIBUTING.md for details.

Security

To report a vulnerability, please use GitHub's private security reporting. See SECURITY.md for details.

License

MIT. See LICENSE.

Metadata

Release files for rockgarden 0.6.4

For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.

Source distribution (sdist)

Source distribution for rockgarden 0.6.4
File Size Uploaded Provenance Actions
rockgarden-0.6.4.tar.gz 612.5 kB Without provenance Details for rockgarden-0.6.4.tar.gz

Built distribution (wheel)

Table of built distributions (wheels) for rockgarden 0.6.4
File Interpreter ABI Platform Actions
rockgarden-0.6.4-py3-none-any.whl Python 3 none any Details for rockgarden-0.6.4-py3-none-any.whl

Total release size: 1.1 MB

Release files / rockgarden-0.6.4.tar.gz

Download URL rockgarden-0.6.4.tar.gz
Size 612.5 kB
Tags Source
SHA-256 checksum
How to use checksums
3872ab6d0c8738721796d0a9bbb4e492f7ab8b5011a43ad27d5e3cc361bce8be
BLAKE2b-256 checksum
How to use checksums
12403ac3abad589e6e0e12d6a33a00a448762a831e4721d768d61a9aefa5e389
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
No
Uploaded via uv/0.9.26 {"installer":{"name":"uv","version":"0.9.26","subcommand":["publish"]},"python":null,"implementation":{"name":null,"version":null},"distro":{"name":"macOS","version":null,"id":null,"libc":null},"system":{"name":null,"release":null},"cpu":null,"openssl_version":null,"setuptools_version":null,"rustc_version":null,"ci":null}

Release files / rockgarden-0.6.4-py3-none-any.whl

Download URL rockgarden-0.6.4-py3-none-any.whl
Size 526.3 kB
Tags Python 3
SHA-256 checksum
How to use checksums
741dba9249f3bfeedabfead51be7149eed306cdbbd3f03550fddffd12a5eb002
BLAKE2b-256 checksum
How to use checksums
01e3595acd015f306db3da2275da228117ac31eab121cecdd95da9c43dba4584
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
No
Uploaded via uv/0.9.26 {"installer":{"name":"uv","version":"0.9.26","subcommand":["publish"]},"python":null,"implementation":{"name":null,"version":null},"distro":{"name":"macOS","version":null,"id":null,"libc":null},"system":{"name":null,"release":null},"cpu":null,"openssl_version":null,"setuptools_version":null,"rustc_version":null,"ci":null}

Security for rockgarden 0.6.4

Provenance

Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.

No provenance found

None of the files in this release were uploaded with provenance metadata.

A note on package security

PyPI is a repository for distributing packages, not a service for auditing them. While third-party security researchers and our staff do their best to detect and remove malicious packages, PyPI cannot guarantee the quality, security or suitability of any given package.

To learn more about protecting yourself from malicious actors, visit our package security documentation.

Anthropic, PBC Visionary sponsor Bloomberg Visionary sponsor Hudson River Trading Visionary sponsor Meta Visionary sponsor NVIDIA Visionary sponsor Microsoft Sustainability sponsor Depot Continuous Integration AWS Cloud computing and Security Sponsor Datadog Monitoring Fastly CDN Google Download Analytics Sentry Error logging StatusPage Status page