oriel

Turn any folder of Markdown into a beautiful website — instantly.

pip install oriel
oriel serve .        # live site → http://127.0.0.1:18787
oriel build .        # or freeze to ./dist to publish

Every Markdown file becomes a page, images become a gallery, and edits refresh the browser on their own. It looks like a publication, not a file listing — with no build step, no front matter, no config.

[!TIP] Especially good for what agents leave behind. Point oriel at a folder Claude Code or a research run just wrote and read it as a real site — dated notes, plots, \(…\) math and all — instead of scrolling raw files. → examples/agent-run

Why not MkDocs / markserv / GitHub?

oriel is the middle that was missing: a tiny read-only server you keep running next to a folder.

What you get

📂 Any folder → a site. Loose Markdown at the top level and subfolders both show up; a root README.md is the home page; images become a gallery. Obsidian vaults and agent dumps work as-is.

✍️ Real Markdown. Syntax-highlighted code with copy buttons, KaTeX math in $…$ or \(…\), tables, an auto table-of-contents, and GitHub-style > [!NOTE] callouts.

🔗 Obsidian & agent-native. [[wikilinks]] / ![[embeds]] resolve, dated notes (YYYY-MM-DD_*.md) become a browsable journal, generated plots collect into a figures wall.

⚡ Live & self-contained. Edits auto-refresh the browser — no manual reload; KaTeX is cached locally so math works offline; light/dark themes with a toggle and six presets.

📊 Dashboards via plugins. Drop in an oriel_plugins.py for custom pages — the bundled example adds run-manifest and LLM-spend dashboards.

🚀 Publish anytime. oriel build freezes everything to static HTML — figures and KaTeX bundled, search still works (client-side index) — ready for GitHub Pages.

Publish (static export)

oriel build .                    # → ./dist, ready to deploy
oriel build docs --base /oriel   # subpath hosting (e.g. project GitHub Pages)

URLs stay identical, math renders offline (bundled KaTeX), and search keeps working via a client-side index. A .nojekyll ships for GitHub Pages.

Configure (optional)

Zero config works. To customize, drop an oriel.toml at the folder root:

title   = "My Notes"
preset  = "ocean"          # terracotta · newsprint · forest · ocean · plum · rose
landing = "guide/intro.md"

…or pick a look from the CLI: oriel serve . --theme forest. Every key is in examples/oriel.toml and the docs.

Plugins

A plugin is a register(site) function that adds pages:

def register(site):
    @site.page("/status", "status")
    def status():                       # return an HTML body; oriel adds the chrome
        return site.markdown((site.root / "STATUS.md").read_text())

See examples/oriel_plugins.py for a real one.

[!WARNING] A plugin is ordinary Python that oriel executes — same trust level as running the repo. Don't point oriel at a folder you don't trust.

Security

oriel is a read-only viewer with a shared-secret key — for a personal machine, an SSH tunnel, or behind a reverse proxy, not a public unauthed service on plain HTTP. See SECURITY.md.

Develop

pip install -e ".[dev]"
make dev      # serve ./docs locally (theme gallery, live reload)
make test     # pytest
make lint     # ruff

make help lists every target. The full docs in docs/ are themselves an oriel site.

An oriel is a bay window that projects out from a wall for a wider view — a window onto a folder.

MIT — see LICENSE.