krz/orgo

Lightning fast org-mode static site generator. fast go org-mode static-site-generator

guide/02-configuration.html

265 lines · 33213 bytes

  1<!DOCTYPE html>
  2<html lang="en">
  3<head>
  4<meta charset="utf-8">
  5<meta name="viewport" content="width=device-width, initial-scale=1">
  6<title>Configuration &middot; orgo</title>
  7<meta name="description" content="Every setting in orgo.toml, what it changes, and what it costs.">
  8<link rel="icon" href="../favicon.svg" type="image/svg+xml">
  9<link rel="stylesheet" href="../theme.css">
 10<link rel="stylesheet" href="../syntax.css">
 11<link rel="stylesheet" href="../style.css">
 12</head>
 13<body>
 14<header class="site">
 15<a class="site-title" href="../index.html">orgo</a>
 16<nav>
 17<a href="../install.html">Install</a>
 18<a href="../quickstart.html">Quick start</a>
 19<a href="index.html">Guide</a>
 20</nav>
 21</header>
 22<main>
 23<h1>Configuration</h1>
 24<p class="lede">All of it optional. A missing config is a valid config.</p>
 25<nav class="toc" aria-label="On this page">
 26<h2>On this page</h2>
 27<ul>
 28<li><a href="#the-whole-file">The whole file</a></li>
 29<li><a href="#site">[site]</a>
 30<ul>
 31<li><a href="#theme">theme</a></li>
 32<li><a href="#base-url">base_url</a></li>
 33</ul></li>
 34<li><a href="#nav">[nav]</a>
 35<ul>
 36<li><a href="#explicit">explicit</a></li>
 37<li><a href="#section-landing-pages-in-the-nav">Section landing pages in the nav</a></li>
 38</ul></li>
 39<li><a href="#"></a>
 40<ul>
 41<li><a href="#which-rule-wins">Which rule wins</a></li>
 42</ul></li>
 43<li><a href="#templates">[templates]</a>
 44<ul>
 45<li><a href="#expose-page-list-costs-incremental-precision">expose_page_list costs incremental precision</a></li>
 46</ul></li>
 47<li><a href="#highlight">[highlight]</a></li>
 48<li><a href="#build">[build]</a>
 49<ul>
 50<li><a href="#sitemap-xml">sitemap.xml</a></li>
 51<li><a href="#static-files-that-live-elsewhere">Static files that live elsewhere</a></li>
 52</ul></li>
 53<li><a href="#html">[html]</a>
 54<ul>
 55<li><a href="#heading-offset">heading_offset</a></li>
 56<li><a href="#section-numbers-differs-from-emacs-on-purpose">section_numbers differs from Emacs on purpose</a></li>
 57</ul></li>
 58<li><a href="#per-file-overrides">Per-file overrides</a></li>
 59<li><a href="#configuration-is-a-cache-input">Configuration is a cache input</a></li>
 60</ul>
 61</nav>
 62<p>orgo looks for <code class="verbatim">orgo.toml</code> in the source directory. Pass a different path with <code class="verbatim">--config</code>. Every field has a default, so a directory of org files with no config still builds a complete site.</p>
 63<p>A <strong>missing</strong> config is normal and silent. A <strong>malformed</strong> one is an error, and an unknown key is rejected by name — a misspelled setting that silently does nothing is how people lose an afternoon.</p>
 64<h2 id="the-whole-file">The whole file</h2>
 65<pre><code class="language-toml highlight"><span class="source toml"><span class="punctuation definition table toml">[</span><span class="entity name section toml">site</span><span class="punctuation definition table toml">]</span>
 66<span class="variable other key toml">title</span> <span class="keyword operator assignment toml">=</span> <span class="string quoted double toml"><span class="punctuation definition string begin toml">&quot;</span>orgo site<span class="punctuation definition string end toml">&quot;</span></span>
 67<span class="variable other key toml">base_url</span> <span class="keyword operator assignment toml">=</span> <span class="string quoted double toml"><span class="punctuation definition string begin toml">&quot;</span><span class="punctuation definition string end toml">&quot;</span></span>
 68<span class="variable other key toml">description</span> <span class="keyword operator assignment toml">=</span> <span class="string quoted double toml"><span class="punctuation definition string begin toml">&quot;</span><span class="punctuation definition string end toml">&quot;</span></span>
 69<span class="variable other key toml">language</span> <span class="keyword operator assignment toml">=</span> <span class="string quoted double toml"><span class="punctuation definition string begin toml">&quot;</span>en<span class="punctuation definition string end toml">&quot;</span></span>
 70<span class="variable other key toml">theme</span> <span class="keyword operator assignment toml">=</span> <span class="string quoted double toml"><span class="punctuation definition string begin toml">&quot;</span><span class="punctuation definition string end toml">&quot;</span></span>
 71
 72<span class="punctuation definition table toml">[</span><span class="entity name section toml">nav</span><span class="punctuation definition table toml">]</span>
 73<span class="variable other key toml">mode</span> <span class="keyword operator assignment toml">=</span> <span class="string quoted double toml"><span class="punctuation definition string begin toml">&quot;</span>top-level<span class="punctuation definition string end toml">&quot;</span></span>
 74<span class="comment line number-sign toml"><span class="punctuation definition comment toml">#</span> pages = [&quot;index.org&quot;, &quot;about.org&quot;]
 75</span>
 76<span class="punctuation definition table toml">[</span><span class="entity name section toml">templates</span><span class="punctuation definition table toml">]</span>
 77<span class="variable other key toml">dir</span> <span class="keyword operator assignment toml">=</span> <span class="string quoted double toml"><span class="punctuation definition string begin toml">&quot;</span>templates<span class="punctuation definition string end toml">&quot;</span></span>
 78<span class="variable other key toml">expose_page_list</span> <span class="keyword operator assignment toml">=</span> <span class="constant language toml">false</span>
 79
 80<span class="punctuation definition table toml">[</span><span class="entity name section toml">highlight</span><span class="punctuation definition table toml">]</span>
 81<span class="variable other key toml">theme</span> <span class="keyword operator assignment toml">=</span> <span class="string quoted double toml"><span class="punctuation definition string begin toml">&quot;</span>InspiredGitHub<span class="punctuation definition string end toml">&quot;</span></span>
 82<span class="variable other key toml">theme_dark</span> <span class="keyword operator assignment toml">=</span> <span class="string quoted double toml"><span class="punctuation definition string begin toml">&quot;</span><span class="punctuation definition string end toml">&quot;</span></span>
 83<span class="variable other key toml">syntaxes_dir</span> <span class="keyword operator assignment toml">=</span> <span class="string quoted double toml"><span class="punctuation definition string begin toml">&quot;</span>syntaxes<span class="punctuation definition string end toml">&quot;</span></span>
 84
 85<span class="punctuation definition table toml">[</span><span class="entity name section toml">build</span><span class="punctuation definition table toml">]</span>
 86<span class="variable other key toml">drafts</span> <span class="keyword operator assignment toml">=</span> <span class="constant language toml">false</span>
 87<span class="variable other key toml">assets</span> <span class="keyword operator assignment toml">=</span> []
 88<span class="variable other key toml">sitemap</span> <span class="keyword operator assignment toml">=</span> <span class="constant language toml">true</span>
 89
 90<span class="punctuation definition table toml">[</span><span class="entity name section toml">html</span><span class="punctuation definition table toml">]</span>
 91<span class="variable other key toml">heading_offset</span> <span class="keyword operator assignment toml">=</span> <span class="constant numeric toml">1</span>
 92<span class="variable other key toml">toc</span> <span class="keyword operator assignment toml">=</span> <span class="constant language toml">true</span>
 93<span class="variable other key toml">section_numbers</span> <span class="keyword operator assignment toml">=</span> <span class="constant language toml">false</span></span></code></pre>
 94<p>Plus any number of <code class="verbatim">[[collections]]</code> blocks, documented in <a href="03-collections.html">Collections</a>.</p>
 95<h2 id="site">[site]</h2>
 96<table>
 97<thead>
 98<tr><th>Key</th><th>Default</th><th>Meaning</th></tr>
 99</thead>
100<tbody>
101<tr><td><code class="verbatim">title</code></td><td><code class="verbatim">"orgo site"</code></td><td>Site name. Available as <code class="verbatim">{{ site.title }}</code>.</td></tr>
102<tr><td><code class="verbatim">base_url</code></td><td>=""</td><td>Absolute origin, <strong>no trailing slash</strong>.</td></tr>
103<tr><td><code class="verbatim">description</code></td><td>=""</td><td>Available as <code class="verbatim">{{ site.description }}</code>.</td></tr>
104<tr><td><code class="verbatim">language</code></td><td><code class="verbatim">"en"</code></td><td>Goes in <code class="verbatim">&lt;html lang&gt;</code> in the built-in layout.</td></tr>
105<tr><td><code class="verbatim">theme</code></td><td>=""</td><td>A built-in stylesheet, written to the output as <code class="verbatim">theme.css</code>.</td></tr>
106</tbody>
107</table>
108<h3 id="theme">theme</h3>
109<p>Four themes are compiled into the binary. Name one and each build writes it to the output root as <code class="verbatim">theme.css</code>, which the built-in layout and the templates <code class="verbatim">orgo init</code> writes both link.</p>
110<table>
111<thead>
112<tr><th>Theme</th><th>Shape</th><th>For</th></tr>
113</thead>
114<tbody>
115<tr><td><code class="verbatim">"plain"</code></td><td>Narrow, system fonts, hairline rules.</td><td>Readable defaults to build your own CSS on.</td></tr>
116<tr><td><code class="verbatim">"blog"</code></td><td>Serif prose, a centred masthead, styled post lists.</td><td>Dated writing.</td></tr>
117<tr><td><code class="verbatim">"wiki"</code></td><td>Wide and dense, contents in the margin, TODO states as badges.</td><td>Notes, a reference site.</td></tr>
118<tr><td><code class="verbatim">"docs"</code></td><td>Narrow, a contents card, quote blocks as notes, <code class="verbatim">#+LEDE:</code>.</td><td>A guide read in order.</td></tr>
119</tbody>
120</table>
121<p>All four follow <code class="verbatim">prefers-color-scheme</code>, so a site gets a dark mode without a toggle, a setting or a line of JavaScript — and all four reflow from a 320px phone up, with tables and code blocks scrolling inside their own box rather than widening the page.</p>
122<p>The default is empty: no stylesheet is written and no page links one, so the output is unstyled HTML. That is deliberate — a site that already ships CSS of its own should not find a second stylesheet competing with it, and upgrading orgo should never restyle a site. An unknown name is an error listing the four.</p>
123<p>A theme styles the markup orgo already emits — headings, tags, TODO keywords, checkbox lists, footnotes, tables — plus the chrome the built-in layout puts around it. There is no theme-specific HTML, so switching or removing one touches no template.</p>
124<p>Every colour is a custom property on <code class="verbatim">:root</code>, named <code class="verbatim">--orgo-*</code>. To adjust rather than replace a theme, ship a stylesheet of your own as an asset, link it after <code class="verbatim">theme.css</code>, and redefine the handful you care about:</p>
125<pre><code class="language-css highlight"><span class="source css"><span class="meta selector css"><span class="entity other pseudo-class css"><span class="punctuation definition entity css">:</span>root</span> </span><span class="meta property-list css"><span class="punctuation section property-list css">{</span>
126  <span class="meta property-name css"><span class="support type custom-property css"><span class="punctuation definition custom-property css">--</span><span class="support type custom-property name css">orgo-accent</span></span></span><span class="punctuation separator key-value css">:</span><span class="meta property-value css"> </span><span class="meta property-value css"><span class="constant other color rgb-value css"><span class="punctuation definition constant css">#</span>7a1fa2</span></span><span class="punctuation terminator rule css">;</span>
127  <span class="meta property-name css"><span class="support type custom-property css"><span class="punctuation definition custom-property css">--</span><span class="support type custom-property name css">orgo-measure</span></span></span><span class="punctuation separator key-value css">:</span><span class="meta property-value css"> </span><span class="meta property-value css"><span class="constant numeric css">46<span class="keyword other unit css">rem</span></span></span><span class="punctuation terminator rule css">;</span>
128</span><span class="punctuation section property-list css">}</span></span></code></pre>
129<p>Code <em>blocks</em> are the one part a built-in theme leaves light in dark mode: <code class="verbatim">syntax.css</code> is coloured by <code class="verbatim">highlight.theme</code>, and that default is a light theme. Two pieces make a block follow <code class="verbatim">prefers-color-scheme</code> — <code class="verbatim">highlight.theme_dark</code> for the tokens, and <code class="verbatim">--orgo-code-bg</code>, <code class="verbatim">--orgo-code-fg</code> and <code class="verbatim">--orgo-code-rule</code> for the surface under them. Set both, or neither and blocks stay light in both schemes. Those three properties colour blocks only — inline <code class="verbatim">~code~</code> follows the page's own scheme, so it stays legible whichever highlight theme you use. The documentation site keeps a dark surface in both schemes instead; its <code class="verbatim">style.css</code> is those three lines and nothing else.</p>
130<p>When you outgrow a theme, drop <code class="verbatim">theme</code> from the config and write <code class="verbatim">templates/base.html</code> against your own CSS. Nothing else changes.</p>
131<h3 id="base-url">base<sub>url</sub></h3>
132<p>Leave it empty and the site is built entirely with relative URLs, which means it works from a subdirectory, from a filesystem path, and from any origin. That portability is why it is the default.</p>
133<p>Set it when you need absolute URLs, which two things require: <strong>feeds</strong>, because a feed is read away from the site that served it, and <strong>canonical links</strong>. The <code class="verbatim">absolute</code> template filter turns a site-root-relative path into a full URL, and errors if there is no base URL to build one from — rather than quietly emitting a relative URL that would make the feed invalid everywhere while looking fine.</p>
134<p>A trailing slash is rejected, because <code class="verbatim">https://example.com/</code> plus <code class="verbatim">blog/x.html</code> is <code class="verbatim">https://example.com//blog/x.html</code>.</p>
135<h2 id="nav">[nav]</h2>
136<p>The navigation shared by every page.</p>
137<table>
138<thead>
139<tr><th><code class="verbatim">mode</code></th><th>Includes</th></tr>
140</thead>
141<tbody>
142<tr><td><code class="verbatim">"top-level"</code> (default)</td><td>Pages at the site root.</td></tr>
143<tr><td><code class="verbatim">"all"</code></td><td>Every page.</td></tr>
144<tr><td><code class="verbatim">"explicit"</code></td><td>Only <code class="verbatim">nav.pages</code>, in the order listed.</td></tr>
145<tr><td><code class="verbatim">"none"</code></td><td>Nothing.</td></tr>
146</tbody>
147</table>
148<p><strong>"all" makes output quadratic.</strong> Each of <em>n</em> pages carries <em>n</em> links, so total output grows with the square of the site. On a 1,790-page site that was 284 MB of mostly navigation. It is fine for a handful of pages and a trap beyond that.</p>
149<p><code class="verbatim">"top-level"</code> keeps the nav a map of the site's top level rather than an index of its contents, so nav size does not depend on how much you write.</p>
150<h3 id="explicit">explicit</h3>
151<pre><code class="language-toml highlight"><span class="source toml"><span class="punctuation definition table toml">[</span><span class="entity name section toml">nav</span><span class="punctuation definition table toml">]</span>
152<span class="variable other key toml">mode</span> <span class="keyword operator assignment toml">=</span> <span class="string quoted double toml"><span class="punctuation definition string begin toml">&quot;</span>explicit<span class="punctuation definition string end toml">&quot;</span></span>
153<span class="variable other key toml">pages</span> <span class="keyword operator assignment toml">=</span> [<span class="string quoted double toml"><span class="punctuation definition string begin toml">&quot;</span>index.org<span class="punctuation definition string end toml">&quot;</span></span>, <span class="string quoted double toml"><span class="punctuation definition string begin toml">&quot;</span>about.org<span class="punctuation definition string end toml">&quot;</span></span>, <span class="string quoted double toml"><span class="punctuation definition string begin toml">&quot;</span>uses.org<span class="punctuation definition string end toml">&quot;</span></span>]</span></code></pre>
154<p>Paths are <strong>source</strong> paths relative to the source root, and the order given is the order rendered — a hand-written nav is a designed sequence, not an alphabetical one. Naming a page that does not exist is an error, because a silently shorter nav is a poor way to learn about a typo.</p>
155<h3 id="section-landing-pages-in-the-nav">Section landing pages in the nav</h3>
156<p>If your sections live in subdirectories, none of them are top-level pages. Put the section's <strong>generated</strong> index in the nav instead, with <code class="verbatim">nav = true</code> on its collection — that is the page a nav entry should point at anyway.</p>
157<p>A generated page has no source file, so name it in <code class="verbatim">pages</code> by its <strong>output</strong> path:</p>
158<pre><code class="language-toml highlight"><span class="source toml"><span class="punctuation definition table toml">[</span><span class="entity name section toml">nav</span><span class="punctuation definition table toml">]</span>
159<span class="variable other key toml">mode</span> <span class="keyword operator assignment toml">=</span> <span class="string quoted double toml"><span class="punctuation definition string begin toml">&quot;</span>explicit<span class="punctuation definition string end toml">&quot;</span></span>
160<span class="variable other key toml">pages</span> <span class="keyword operator assignment toml">=</span> [<span class="string quoted double toml"><span class="punctuation definition string begin toml">&quot;</span>blog/index.html<span class="punctuation definition string end toml">&quot;</span></span>, <span class="string quoted double toml"><span class="punctuation definition string begin toml">&quot;</span>garden/index.html<span class="punctuation definition string end toml">&quot;</span></span>, <span class="string quoted double toml"><span class="punctuation definition string begin toml">&quot;</span>about.org<span class="punctuation definition string end toml">&quot;</span></span>]</span></code></pre>
161<p>That is the only way to interleave the two: a collection that sets <code class="verbatim">nav = true</code> without being listed is appended after everything you did list, so <code class="verbatim">"about.org"</code> alone would put <code class="verbatim">About</code> first and the sections after it. Listing all of them puts each exactly where you said. Either spelling works for an authored page too — its source path or its output path — though the source path is the one that survives a <code class="verbatim">#+SLUG:</code>.</p>
162<h2><a href="pages">pages</a></h2>
163<p>Which layout a page renders through. Without any of these, every authored page uses <code class="verbatim">base.html</code>.</p>
164<pre><code class="language-toml highlight"><span class="source toml"><span class="punctuation definition table array toml">[[</span><span class="entity name section toml">pages</span><span class="punctuation definition table array toml">]]</span>
165<span class="variable other key toml">match</span> <span class="keyword operator assignment toml">=</span> <span class="string quoted double toml"><span class="punctuation definition string begin toml">&quot;</span>blog<span class="punctuation definition string end toml">&quot;</span></span>
166<span class="variable other key toml">template</span> <span class="keyword operator assignment toml">=</span> <span class="string quoted double toml"><span class="punctuation definition string begin toml">&quot;</span>post.html<span class="punctuation definition string end toml">&quot;</span></span></span></code></pre>
167<p><code class="verbatim">match</code> is a <strong>source</strong> path relative to the source root — a directory, covering every page beneath it however deep, or one <code class="verbatim">.org</code> file. It is matched by path component, so <code class="verbatim">blog</code> covers <code class="verbatim">blog/2026/post.org</code> and does not touch <code class="verbatim">blogroll.org</code>.</p>
168<p>A section's layout is a property of the section, which is why this is a rule and not something you write in each file: a blog post carries the same byline and reply footer as every other one, and repeating that in 200 files means maintaining one fact 200 times.</p>
169<h3 id="which-rule-wins">Which rule wins</h3>
170<p>Most specific, by path depth — <code class="verbatim">blog/notes</code> beats <code class="verbatim">blog</code>, whatever order they appear in. An empty <code class="verbatim">match</code> covers the whole site, which is how you rename the default layout.</p>
171<p>A page that differs from its section says so itself, and that wins over any rule:</p>
172<pre><code class="language-org highlight"><span class="text org"><span class="keyword other keyword org">#+TITLE:</span><span class="string unquoted org"> Colophon</span>
173<span class="keyword other keyword org">#+TEMPLATE:</span><span class="string unquoted org"> wide.html</span></span></code></pre>
174<p>Naming a template that is not in the templates directory is an error that names the page, the template and what does exist — a layout typo should not be a hunt.</p>
175<h2 id="templates">[templates]</h2>
176<table>
177<thead>
178<tr><th>Key</th><th>Default</th><th>Meaning</th></tr>
179</thead>
180<tbody>
181<tr><td><code class="verbatim">dir</code></td><td><code class="verbatim">"templates"</code></td><td>Directory of templates, relative to the source root.</td></tr>
182<tr><td><code class="verbatim">expose_page_list</code></td><td><code class="verbatim">false</code></td><td>Give every template a <code class="verbatim">pages</code> list of all page metadata.</td></tr>
183</tbody>
184</table>
185<h3 id="expose-page-list-costs-incremental-precision">expose<sub>page</sub><sub>list</sub> costs incremental precision</h3>
186<p>With it on, any page can read every page's metadata — so adding one page can change any page's output, and the whole site must re-render on every add, rename or retitle. That is the trade for building an index by hand in a template. Most people want a <a href="03-collections.html">collection</a> instead, which gets the same result while keeping adding a post a one-page rebuild.</p>
187<h2 id="highlight">[highlight]</h2>
188<table>
189<thead>
190<tr><th>Key</th><th>Default</th><th>Meaning</th></tr>
191</thead>
192<tbody>
193<tr><td><code class="verbatim">theme</code></td><td><code class="verbatim">"InspiredGitHub"</code></td><td>A syntect theme name.</td></tr>
194<tr><td><code class="verbatim">theme_dark</code></td><td><code class="verbatim">""</code></td><td>A second theme for readers in dark mode.</td></tr>
195<tr><td><code class="verbatim">syntaxes_dir</code></td><td><code class="verbatim">"syntaxes"</code></td><td>Extra <code class="verbatim">.sublime-syntax</code> files.</td></tr>
196</tbody>
197</table>
198<p>Any theme syntect ships: <code class="verbatim">InspiredGitHub</code>, <code class="verbatim">Solarized (dark)</code>, <code class="verbatim">Solarized (light)</code>, <code class="verbatim">base16-ocean.dark</code>, <code class="verbatim">base16-ocean.light</code>, <code class="verbatim">base16-eighties.dark</code>, <code class="verbatim">base16-mocha.dark</code>. An unknown name is an error listing the valid ones.</p>
199<p><code class="verbatim">theme_dark</code> is off by default, and one theme colours every reader. Name a second one and <code class="verbatim">syntax.css</code> carries both, each behind the <code class="verbatim">prefers-color-scheme</code> query it belongs to, so a reader's system picks the colours — one stylesheet, no JavaScript, nothing extra for a layout to link:</p>
200<pre><code class="language-toml highlight"><span class="source toml"><span class="punctuation definition table toml">[</span><span class="entity name section toml">highlight</span><span class="punctuation definition table toml">]</span>
201<span class="variable other key toml">theme</span> <span class="keyword operator assignment toml">=</span> <span class="string quoted double toml"><span class="punctuation definition string begin toml">&quot;</span>InspiredGitHub<span class="punctuation definition string end toml">&quot;</span></span>
202<span class="variable other key toml">theme_dark</span> <span class="keyword operator assignment toml">=</span> <span class="string quoted double toml"><span class="punctuation definition string begin toml">&quot;</span>base16-ocean.dark<span class="punctuation definition string end toml">&quot;</span></span></span></code></pre>
203<p>Only the token colours change with the scheme. The surface a block sits on is the page's, so give your dark mode a dark <code class="verbatim">pre</code> background — a dark theme's colours are chosen for one — with <code class="verbatim">--orgo-code-bg</code> under a built-in theme, or your own CSS.</p>
204<p>The two themes are separated rather than stacked because they name different scopes: a light theme's <code class="verbatim">.source.python .keyword</code> outranks a dark theme's <code class="verbatim">.keyword</code>, so appending one to the other would leave light colours on some tokens. The cost of the separation is that a browser too old to know <code class="verbatim">prefers-color-scheme</code> matches neither query and shows code unhighlighted. Leaving <code class="verbatim">theme_dark</code> empty keeps the unconditional rules of before.</p>
205<p>Highlighting emits <strong>CSS classes</strong>, never inline styles, so themes live in a stylesheet. Each build writes <code class="verbatim">syntax.css</code> into the output and every page links it.</p>
206<p>orgo bundles TOML and Org on top of syntect's built-in languages. Anything else missing is a file away: put a <code class="verbatim">.sublime-syntax</code> definition in <code class="verbatim">syntaxes_dir</code> and it is loaded. A definition that fails to parse is reported and skipped, because one bad file should not stop a site from building.</p>
207<h2 id="build">[build]</h2>
208<table>
209<thead>
210<tr><th>Key</th><th>Default</th><th>Meaning</th></tr>
211</thead>
212<tbody>
213<tr><td><code class="verbatim">drafts</code></td><td><code class="verbatim">false</code></td><td>Include pages marked <code class="verbatim">#+DRAFT:</code>.</td></tr>
214<tr><td><code class="verbatim">assets</code></td><td><code class="verbatim">[]</code></td><td>Extra directories copied to the <strong>site root</strong>.</td></tr>
215<tr><td><code class="verbatim">sitemap</code></td><td><code class="verbatim">true</code></td><td>Write <code class="verbatim">sitemap.xml</code>. Needs <code class="verbatim">site.base_url</code>.</td></tr>
216</tbody>
217</table>
218<p><code class="verbatim">--drafts</code> on the command line turns this on for one run. The flag can only turn drafts on; it never turns off a config that asked for them.</p>
219<h3 id="sitemap-xml">sitemap.xml</h3>
220<p>Every page the build emits, generated ones included — a crawler has no other way to learn that <code class="verbatim">/blog/</code> exists. <code class="verbatim">lastmod</code> is the page's own <code class="verbatim">#+DATE:</code> where it has one, and absent where it does not: a filesystem timestamp would say the day you cloned the repository.</p>
221<p><strong>Nothing is written until <code class="verbatim">site.base_url</code> is set.</strong> A sitemap has nowhere to put a relative URL, so a zero-config build produces no sitemap rather than an invalid one. Set a base URL and it appears; set <code class="verbatim">sitemap = false</code> and it does not.</p>
222<h3 id="static-files-that-live-elsewhere">Static files that live elsewhere</h3>
223<p>A site's static files do not always sit where its writing does. weblorg publishes <code class="verbatim">theme/static/</code> at <code class="verbatim">/</code>, and a repository migrating from it should not have to move <code class="verbatim">robots.txt</code> next to its blog posts to keep the URL:</p>
224<pre><code class="language-toml highlight"><span class="source toml"><span class="punctuation definition table toml">[</span><span class="entity name section toml">build</span><span class="punctuation definition table toml">]</span>
225<span class="variable other key toml">assets</span> <span class="keyword operator assignment toml">=</span> [<span class="string quoted double toml"><span class="punctuation definition string begin toml">&quot;</span>../theme/static<span class="punctuation definition string end toml">&quot;</span></span>]</span></code></pre>
226<p>Paths are relative to the source root and may point outside it. Each directory's <strong>contents</strong> land at the site root — <code class="verbatim">theme/static/img/logo.svg</code> publishes at <code class="verbatim">/img/logo.svg</code>, not <code class="verbatim">/static/img/logo.svg</code>.</p>
227<p>Two files claiming one URL is a build error naming both, rather than a coin flip decided by directory order. A path that is not a directory is an error too, since it is a typo.</p>
228<p>Under <code class="verbatim">watch</code> and <code class="verbatim">serve</code> these directories are watched as well, so editing a stylesheet outside the source tree still reloads the page.</p>
229<h2 id="html">[html]</h2>
230<table>
231<thead>
232<tr><th>Key</th><th>Default</th><th>Meaning</th></tr>
233</thead>
234<tbody>
235<tr><td><code class="verbatim">heading_offset</code></td><td><code class="verbatim">1</code></td><td>Added to every org heading level.</td></tr>
236<tr><td><code class="verbatim">toc</code></td><td><code class="verbatim">true</code></td><td>Make <code class="verbatim">page.toc</code> available to templates.</td></tr>
237<tr><td><code class="verbatim">section_numbers</code></td><td><code class="verbatim">false</code></td><td>Number headings <code class="verbatim">1.</code>, <code class="verbatim">1.1.</code>, …</td></tr>
238</tbody>
239</table>
240<h3 id="heading-offset">heading<sub>offset</sub></h3>
241<p>A level-1 org heading renders as <code class="verbatim">&lt;h2&gt;</code> by default, because the layout supplies the page title as the <code class="verbatim">&lt;h1&gt;</code>. This matches Emacs, whose <code class="verbatim">org-html-toplevel-hlevel</code> is 2 for the same reason.</p>
242<p>Set it to <code class="verbatim">0</code> if your template renders no title of its own — otherwise the document starts at <code class="verbatim">&lt;h2&gt;</code> with nothing above it.</p>
243<h3 id="section-numbers-differs-from-emacs-on-purpose">section<sub>numbers</sub> differs from Emacs on purpose</h3>
244<p><code class="verbatim">org-export-with-section-numbers</code> is on in Emacs, so an org-published site inherits numbered headings whether or not anyone chose them. Most sites do not want them, so the default here is the taste rather than the inheritance. Turning it on emits Emacs' own <code class="verbatim">section-number-N</code> classes.</p>
245<h2 id="per-file-overrides">Per-file overrides</h2>
246<p>Org's own <code class="verbatim">#+OPTIONS:</code> switches override the site setting for one document:</p>
247<pre><code class="language-org highlight"><span class="text org"><span class="keyword other keyword org">#+OPTIONS:</span><span class="string unquoted org"> toc:nil num:t</span></span></code></pre>
248<table>
249<thead>
250<tr><th>Switch</th><th>Overrides</th></tr>
251</thead>
252<tbody>
253<tr><td><code class="verbatim">toc:nil</code> / <code class="verbatim">toc:t</code></td><td><code class="verbatim">[html] toc</code></td></tr>
254<tr><td><code class="verbatim">num:t</code> / <code class="verbatim">num:nil</code></td><td><code class="verbatim">[html] section_numbers</code></td></tr>
255</tbody>
256</table>
257<p>Off is spelled <code class="verbatim">nil</code>, <code class="verbatim">false</code>, <code class="verbatim">no</code>, <code class="verbatim">0</code> or <code class="verbatim">off</code>; anything else is on.</p>
258<h2 id="configuration-is-a-cache-input">Configuration is a cache input</h2>
259<p>The resolved config is hashed into every page's render key, so editing <code class="verbatim">orgo.toml</code> re-renders exactly the pages it affects — which for most settings is all of them. You never need <code class="verbatim">--no-cache</code> after a config change.</p>
260</main>
261<footer class="site">
262Built with orgo &mdash; these docs are an orgo site.
263</footer>
264</body>
265</html>