Quickstart

Install

pip install oriel

A small, pure-Python package: markdown-it-py (Markdown + KaTeX math) comes with it, so prose renders out of the box — nothing else to install.

Zero-install from a checkout works too:

uv run python -m oriel serve   # serves the current directory

Serve a folder

oriel serve ~/dev/my-project

oriel prints a URL with a secret key:

serving ~/dev/my-project  (config: auto (2 markdown dirs))
serving at http://127.0.0.1:18787/?key=Xy...

Open that URL once per browser; a cookie keeps you signed in. Every top-level directory with Markdown is now a tab. Edit a file and refresh — the change is there. (--no-auth drops the key; --host 0.0.0.0 exposes it on the LAN, but read Security first.)

Point it at agent output

Nothing special to do — oriel already handles what agents produce:

oriel serve ./some-agent-run

Dated notes become a journal, \(…\) / \[…\] math renders, and generated plots collect into a figures wall. There's a worked example in examples/agent-run.

Build a static site

When you want to hand it to someone who won't run a server:

oriel build ~/dev/my-project           # -> ./dist, ready to deploy

See Static export for options and hosting notes.

Common flags

Next: Static export.