Getting Started
Contents
Requirements: Python 3.11+
OnyxFolio works with any Markdown editor — even a plain text editor. For the full experience (wiki-links, Dataview, callouts, transclusions), use Obsidian. Foam (VS Code) is the closest alternative with compatible syntax.
Running locally
git clone https://github.com/airenare/onyxfolio
cd onyxfolio
pip install -r requirements.txt
# Point at your vault (or omit to use the bundled demo vault)
echo "VAULT_PATH=/path/to/your/vault" > .env
python3 app.py
# → http://127.0.0.1:8000
The server hot-reloads when vault files change. No restart needed.
Docker
Mount a local vault directory:
docker build -t onyxfolio .
docker run -p 8000:8000 -v /path/to/vault:/vault onyxfolio
Or use docker-compose.yml with a .env file to clone a private vault repo at build time — see Deployment for details.
If /vault is not mounted or doesn't exist, the server falls back to the bundled BlogPages/ demo vault.
Publishing your first note
Add website: true to a note's frontmatter:
---
website: true
title: My First Post
date: 2026-01-15
tags:
- hello
---
Your content here.
The note is now live. Its URL is derived from its folder path and title.
Vault structure basics
| Vault path | URL |
|---|---|
Home.md (with type: homepage) |
/ |
blog/Blog.md (with type: listing) |
/blog |
blog/My Post.md |
/blog/my-post |
About.md |
/about |
See Features for the full frontmatter reference.
Frontmatter reference
---
website: true # required to publish
type: homepage # homepage | listing | book
title: My Post # overrides H1 and filename
date: 2026-01-15
slug: my-post # auto-generated from title if omitted
summary: "..." # shown on listing cards; auto-derived if omitted
featured: true # highlight in the section's featured area
priority: 0 # featured posts: lower = higher rank
menu_order: 1 # pin to top nav; lower = further left
show_search: true # root homepage only: adds Search to nav
show_tags: true # root homepage only: adds Tags to nav
banner: "https://example.com/image.jpg"
banner_x: 0.5 # focal point 0–1
banner_y: 0.4
author: "Jane Doe"
updated: 2026-04-01 # shown as "Updated …" in post meta
tags:
- python
- philosophy
aliases:
- alternate name
---
YAML colon rule
Any string value containing a colon must be wrapped in double quotes, otherwise YAML breaks it silently.
title: "From Vault to Web: How This Works" # correct
title: From Vault to Web: How This Works # broken