A static site generator for your markdown vault. A flexible, configurable alternative to Obsidian Publish.
cd my-vault
uvx foliate init # Create .foliate/config.toml
uvx foliate build # Generate site to .foliate/build/- Everything in your vault - All content, config, and output stay in your vault
- Single executable - One tool to generate your website, no complex setup
- Flexible - Just markdown files in, a website out
- Zero config - Works out of the box with sensible defaults
- Vault-native - Everything lives in
.foliate/inside your vault - Two-tiered visibility - Control what's public vs. published
- Incremental builds - Only rebuilds changed files (auto-rebuilds on config/template changes)
- Watch mode - Auto-rebuild on file changes
- Works with any markdown - Obsidian, Logseq, or plain markdown files
- Obsidian syntax - Supports
image sizing - Quarto support - Preprocess
.qmdfiles (optional) - Deploy command - Built-in GitHub Pages deployment
# Initialize in your vault
cd my-vault
uvx foliate init
# Build
uvx foliate build
# Watch mode (build + serve + auto-rebuild)
uvx foliate watchmy-vault/
├── .foliate/
│ ├── config.toml # Configuration
│ ├── build/ # Generated site
│ ├── cache/ # Build cache
│ ├── templates/ # Custom templates (optional)
│ └── static/ # Custom CSS/JS (optional)
├── _private/ # Ignored - never built
├── _homepage/ # Site root (/, /about/, etc.)
│ └── about.md # → example.com/about/
├── assets/ # Images, PDFs
├── Home.md # → example.com/wiki/Home/
└── Notes/
└── ideas.md # → example.com/wiki/Notes/ideas/
| Directory | Purpose |
|---|---|
_private/ |
Never built, regardless of frontmatter. Configurable via ignored_folders in config. |
_homepage/ |
Content deployed to site root (/) instead of /wiki/ (or other prefix). Excluded from normal wiki generation. |
Control what gets built and listed:
---
public: true # Built and accessible via direct link
published: true # Also appears in listings and search
---- No frontmatter or
public: false→ Not built (private) public: true→ Built, accessible via URLpublic: true, published: true→ Built AND visible in listings
.foliate/config.toml:
[site]
name = "My Wiki"
url = "https://example.com"
[build]
ignored_folders = ["_private", "drafts"]
wiki_prefix = "wiki" # URL prefix for wiki content (set to "" for root)
[nav]
items = [
{ url = "/about/", label = "About" },
{ url = "/wiki/Home/", label = "Wiki" },
]foliate init # Create .foliate/config.toml
foliate build # Build site
foliate watch # Build + serve + auto-rebuild
foliate deploy # Deploy to GitHub Pages
foliate clean # Remove build artifactsfoliate build --force # Force full rebuild
foliate build --verbose # Detailed output
foliate build --serve # Start server after build
foliate watch --port 3000 # Custom port
foliate deploy --dry-run # Preview deploy without executing
foliate deploy -m "msg" # Custom commit messageFoliate generates static files in .foliate/build/. Deploy anywhere that serves static files.
Configure in .foliate/config.toml:
[deploy]
method = "github-pages"
target = "../username.github.io" # Path to your GitHub Pages repo
exclude = ["CNAME", ".gitignore", ".gitmodules"]Then deploy:
foliate deploy # Sync, commit, and push
foliate deploy --dry-run # Preview changes firstrsync -avz --delete .foliate/build/ user@server:/var/www/mysite/cp -r .foliate/build/* /path/to/webserver/Foliate is designed to be customized via template and CSS overrides.
my-vault/
└── .foliate/
├── templates/ # Override layout.html, page.html
└── static/ # Override main.css, add custom assets
Files in these directories take precedence over Foliate's defaults.
See docs/customization.md for the full guide, including:
- Template variables reference
- CSS variables for theming
- Common customization examples:
Foliate can preprocess .qmd files (Quarto markdown) to .md before building:
# Install with quarto support
pip install foliate[quarto]Configure in .foliate/config.toml:
[advanced]
quarto_enabled = true
quarto_python = "/path/to/python" # Optional: Python for QuartoFoliate uses a cross-platform GitHub Actions CI workflow on pull requests and main pushes:
- Test matrix: Linux, macOS, Windows on Python 3.12 and 3.13
- Build + smoke matrix: Linux, macOS, Windows (Python 3.13), including wheel install and CLI smoke checks
Releases remain manual via:
make publishFor the complete maintainer release process, see docs/releasing.md.
MIT