krz/orgo

  1#+TITLE: Command reference
  2#+DESCRIPTION: Every command and flag, and what each is actually for.
  3#+LEDE: Six commands: build, serve, watch, audit, init, clean.
  4
  5* The two paths
  6
  7=build=, =serve= and =watch= all take the same pair:
  8
  9#+BEGIN_SRC sh
 10orgo <command> <SOURCE> -o <OUTPUT>
 11#+END_SRC
 12
 13*SOURCE is the URL root*, not "the project". =SOURCE/blog/post.org= is published at
 14=/blog/post.html=, so if your writing lives in a =content/= subdirectory you point at
 15=content/= and not at the repository around it. Choosing the directory above the one you
 16meant still builds — it just prefixes every URL with that directory's name and copies
 17your build scripts in as assets. [[file:../quickstart.org][Quick start]] works through it.
 18
 19*OUTPUT* may live inside the source; it is recognised and skipped, so a build never
 20consumes its own output.
 21
 22* build
 23
 24#+BEGIN_SRC sh
 25orgo build <INPUT> -o <OUTPUT> [--no-cache] [--strict] [--drafts] [--config FILE]
 26#+END_SRC
 27
 28If =INPUT= is a directory, it is walked and built into a linked site at =OUTPUT=. If it
 29is a single =.org= file, one HTML file is written — useful for one-off conversions,
 30though with no other documents to resolve against, internal links keep a best-effort URL.
 31
 32| Flag | Effect |
 33|------+--------|
 34| =-o, --output= | Output directory (or =.html= file for single-file input). Required for a site. |
 35| =--no-cache= | Ignore the incremental cache and re-render every page. |
 36| =--strict= | Broken internal links and parse diagnostics become a non-zero exit. |
 37| =--drafts= | Include pages marked =#+DRAFT:=. |
 38| =--config FILE= | Use this config instead of =orgo.toml= in the source directory. |
 39
 40The summary line reports what happened:
 41
 42#+BEGIN_EXAMPLE
 43built 182 page(s) (4 rendered, 178 cached), copied 3 asset(s) from src -> _site (0 unresolved link(s), 0 diagnostic(s))
 44#+END_EXAMPLE
 45
 46=rendered= is the invalidation set — the pages that actually needed rewriting. On a
 47second build with nothing changed it is zero.
 48
 49** --strict is for CI
 50
 51Without it, a broken link is a warning and the build succeeds. With it, the build fails
 52and names every problem. Use it wherever a bad build should not ship:
 53
 54#+BEGIN_SRC sh
 55orgo build content -o _site --strict
 56#+END_SRC
 57
 58* serve
 59
 60#+BEGIN_SRC sh
 61orgo serve <INPUT> -o <OUTPUT> [-p PORT] [--host HOST] [--drafts] [--config FILE]
 62#+END_SRC
 63
 64Builds, watches, serves, and reloads the browser when a rebuild lands. This is the
 65command to use while writing.
 66
 67| Flag | Default | Effect |
 68|------+---------+--------|
 69| =-p, --port= | =3000= | Port to listen on. |
 70| =--host= | =127.0.0.1= | Address to bind. |
 71| =--drafts= | off | Include =#+DRAFT:= pages, so you can see what you are writing. |
 72
 73*It binds loopback on purpose.* A development server serves unreviewed drafts off your
 74laptop, so reaching the local network is something you ask for:
 75
 76#+BEGIN_SRC sh
 77orgo serve content -o _site --host 0.0.0.0
 78#+END_SRC
 79
 80The live-reload script is injected into responses and never written to disk, so what you
 81deploy stays clean. Details in [[file:../guide/08-workflow.org][Watching and serving]].
 82
 83* watch
 84
 85#+BEGIN_SRC sh
 86orgo watch <INPUT> -o <OUTPUT> [--no-cache] [--strict] [--drafts] [--config FILE]
 87#+END_SRC
 88
 89Rebuilds on filesystem events with no server — for when something else is already serving
 90the output, or you just want the build to keep up as you write.
 91
 92* audit
 93
 94#+BEGIN_SRC sh
 95orgo audit <INPUT>
 96#+END_SRC
 97
 98Reports which org constructs a corpus uses and how they land against what orgo
 99supports, plus a census of every keyword, block type, drawer and link scheme seen. Point
100it at your notes before trusting a tool with them. See [[file:../guide/09-auditing.org][Auditing a corpus]].
101
102It prints names, counts and =file:line= locations — never document text — so an audit of
103private notes is safe to share.
104
105* init
106
107#+BEGIN_SRC sh
108orgo init [DIRECTORY]
109#+END_SRC
110
111Scaffolds a working site: a fully commented config, an editable copy of the built-in
112layout, listing and tag templates, an RSS template, a home page and a first post.
113Defaults to the current directory.
114
115Only files that do not already exist are written, so it is safe to run inside a directory
116that already has content — it fills in what is missing and leaves the rest alone.
117
118* clean
119
120#+BEGIN_SRC sh
121orgo clean <OUTPUT>
122#+END_SRC
123
124Removes the output directory, including the incremental cache manifest inside it. You
125rarely need this: the cache is versioned and discards itself when it stops being valid.
126
127* Exit codes
128
129| Code | Meaning |
130|------+---------|
131| =0= | Success. Warnings may still have been printed. |
132| =1= | The build failed, or =--strict= found problems. |
133
134Diagnostics are printed as =file:line: message=, the form an editor can jump to:
135
136#+BEGIN_EXAMPLE
137warning: blog/post.org:42: unterminated `#+BEGIN_SRC` block (no `#+END_SRC`); everything to the end of the file was read as block content
138warning: index.org: unresolved link [[#setup]]
139#+END_EXAMPLE