docs/index.org
80 lines · 3678 bytes
orgo
orgo turns a directory of .org files into a static website. It treats org as the
source language: the org element tree — headings, drawers, blocks, links with their
org-specific semantics — is the document model, and that tree is rendered straight to
HTML. There is no markdown-shaped intermediate representation, because the point is to
preserve what markdown cannot express.
cargo run -- init my-site
cargo run -- serve my-site -o _site
Open 127.0.0.1:3000, edit any .org file, and the browser reloads itself.
Start here
- Install — get the binary built and on your PATH.
- Quick start — a working site in two commands, then your own content.
- The guide — every command, setting, template variable and org construct.
What you get with no configuration at all
Point it at a directory of org files and you get a complete site: pages, navigation,
syntax-highlighted code, and the stylesheet that colours it. Nothing about your files has
to change, and no orgo.toml is required.
orgo build ~/notes -o _siteConfiguration changes what you get. It is never what makes it work.
What it does that is unusual
Incremental builds are the architecture
Every page has a render key composed from its content, its resolved links, the site config and the templates. Editing one post re-renders that post, its section index, its tag pages, and the tag index whose counts changed — four pages, whatever the size of the site. A full build and an incremental build produce byte-identical output, and a test proves it.
It is measured against Emacs
cargo test --test oracle exports each test fixture with org's own HTML exporter through
emacs --batch and records the disagreement. Heading structure, list nesting and
source-block text match exactly. Everything that still differs is a deliberate choice,
listed in Org support.
It tells you what your corpus actually uses
orgo audit ~/notes
The audit reports which org constructs appear in a corpus, how often, and whether each is
supported — so you can find out before you trust a tool with your writing. It reports
names, counts and file:line locations only, never document text, so auditing private
notes stays safe to paste into an issue.
Feature summary
| Area | What is there |
|---|---|
| Org syntax | headings with TODO/priority/tags, lists (nested, description, checkboxes), tables, source blocks, quote/center/example/export blocks, footnotes, timestamps, links, images with captions |
| Output | syntax highlighting via syntect, table of contents, section numbers, heading anchors |
| Structure | #+SLUG: URLs, drafts, generated listing pages, tag pages and tag indexes, pagination, RSS feeds |
| Templates | minijinja layouts with inheritance, rich page metadata, custom filters |
| Workflow | incremental rebuilds, watch on filesystem events, serve with live reload |
| Confidence | 152 tests, an emacs --batch differential oracle, a corpus audit tool |
Status
This documentation site is itself an orgo site — the sources are in docs/ and it is
built with the command in Quick start. If a feature is described here, it is being used
to render the page describing it.