krz/orgo

 1#+TITLE: orgo
 2#+DESCRIPTION: An org-mode static site generator in Rust, where the org element tree is the document model.
 3#+LEDE: Org is the source language, not an inconvenient input to be normalised into markdown.
 4#+OPTIONS: toc:nil
 5
 6orgo turns a directory of =.org= files into a static website. It treats org as the
 7*source language*: the org element tree — headings, drawers, blocks, links with their
 8org-specific semantics — /is/ the document model, and that tree is rendered straight to
 9HTML. There is no markdown-shaped intermediate representation, because the point is to
10preserve what markdown cannot express.
11
12#+BEGIN_SRC sh
13cargo run -- init my-site
14cargo run -- serve my-site -o _site
15#+END_SRC
16
17Open [[http://127.0.0.1:3000][127.0.0.1:3000]], edit any =.org= file, and the browser reloads itself.
18
19* Start here
20
21- [[file:install.org][Install]] — get the binary built and on your PATH.
22- [[file:quickstart.org][Quick start]] — a working site in two commands, then your own content.
23- [[file:guide/01-cli.org][The guide]] — every command, setting, template variable and org construct.
24
25* What you get with no configuration at all
26
27Point it at a directory of org files and you get a complete site: pages, navigation,
28syntax-highlighted code, and the stylesheet that colours it. Nothing about your files has
29to change, and no =orgo.toml= is required.
30
31#+BEGIN_SRC sh
32orgo build ~/notes -o _site
33#+END_SRC
34
35Configuration changes what you get. It is never what makes it work.
36
37* What it does that is unusual
38
39** Incremental builds are the architecture
40
41Every page has a render key composed from its content, its resolved links, the site
42config and the templates. Editing one post re-renders that post, its section index, its
43tag pages, and the tag index whose counts changed — four pages, whatever the size of the
44site. A full build and an incremental build produce byte-identical output, and a test
45proves it.
46
47** It is measured against Emacs
48
49=cargo test --test oracle= exports each test fixture with org's own HTML exporter through
50=emacs --batch= and records the disagreement. Heading structure, list nesting and
51source-block text match exactly. Everything that still differs is a deliberate choice,
52listed in [[file:guide/05-org-support.org][Org support]].
53
54** It tells you what your corpus actually uses
55
56#+BEGIN_SRC sh
57orgo audit ~/notes
58#+END_SRC
59
60The audit reports which org constructs appear in a corpus, how often, and whether each is
61supported — so you can find out before you trust a tool with your writing. It reports
62names, counts and =file:line= locations only, never document text, so auditing private
63notes stays safe to paste into an issue.
64
65* Feature summary
66
67| Area | What is there |
68|------+---------------|
69| 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 |
70| Output | syntax highlighting via syntect, table of contents, section numbers, heading anchors |
71| Structure | =#+SLUG:= URLs, drafts, generated listing pages, tag pages and tag indexes, pagination, RSS feeds |
72| Templates | minijinja layouts with inheritance, rich page metadata, custom filters |
73| Workflow | incremental rebuilds, =watch= on filesystem events, =serve= with live reload |
74| Confidence | 152 tests, an =emacs --batch= differential oracle, a corpus audit tool |
75
76* Status
77
78This documentation site is itself an orgo site — the sources are in =docs/= and it is
79built with the command in [[file:quickstart.org][Quick start]]. If a feature is described here, it is being used
80to render the page describing it.