krz/orgo

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

quickstart.html

177 lines · 25584 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>Quick start &middot; orgo</title>
  7<meta name="description" content="A working site in two commands, then your own writing, then your own design.">
  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="#">Quick start</a>
 19<a href="guide/index.html">Guide</a>
 20</nav>
 21</header>
 22<main>
 23<h1>Quick start</h1>
 24<p class="lede">Five minutes from nothing to a site that reloads as you type.</p>
 25<nav class="toc" aria-label="On this page">
 26<h2>On this page</h2>
 27<ul>
 28<li><a href="#two-commands">Two commands</a>
 29<ul>
 30<li><a href="#what-init-created">What init created</a></li>
 31</ul></li>
 32<li><a href="#adapting-it-to-org-files-you-already-have">Adapting it to org files you already have</a>
 33<ul>
 34<li><a href="#source-is-the-url-root">SOURCE is the URL root</a></li>
 35<li><a href="#common-layouts">Common layouts</a></li>
 36<li><a href="#output-can-live-inside-the-source">OUTPUT can live inside the source</a></li>
 37<li><a href="#where-config-and-templates-go">Where config and templates go</a></li>
 38<li><a href="#a-worked-example">A worked example</a></li>
 39</ul></li>
 40<li><a href="#write-a-page">Write a page</a>
 41<ul>
 42<li><a href="#control-the-url">Control the URL</a></li>
 43<li><a href="#keep-something-unfinished-out-of-the-build">Keep something unfinished out of the build</a></li>
 44</ul></li>
 45<li><a href="#change-the-design">Change the design</a></li>
 46<li><a href="#add-a-blog-index">Add a blog index</a></li>
 47<li><a href="#build-for-real">Build for real</a></li>
 48<li><a href="#next">Next</a></li>
 49</ul>
 50</nav>
 51<h2 id="two-commands">Two commands</h2>
 52<pre><code class="language-sh highlight"><span class="source shell bash"><span class="meta function-call shell"><span class="variable function shell">orgo</span></span><span class="meta function-call arguments shell"> init my-site</span>
 53<span class="meta function-call shell"><span class="variable function shell">orgo</span></span><span class="meta function-call arguments shell"> serve my-site<span class="variable parameter option shell"><span class="punctuation definition parameter shell"> -</span>o</span> _site</span></span></code></pre>
 54<p>Open <a href="http://127.0.0.1:3000">127.0.0.1:3000</a>. Edit <code class="verbatim">my-site/index.org</code> in your editor, save, and the page reloads on its own.</p>
 55<p><code class="verbatim">init</code> writes only files that do not already exist, so running it inside a directory that already has content is safe and additive.</p>
 56<h3 id="what-init-created">What init created</h3>
 57<pre>my-site/
 58  orgo.toml            every setting, commented — all at their defaults but `theme`
 59  index.org               the home page
 60  blog/first-post.org     a post, to show the collection working
 61  templates/
 62    base.html             the page layout — edit this
 63    list.html             the blog index
 64    tags.html             the tag index
 65    feed.xml              an RSS feed</pre>
 66<h2 id="adapting-it-to-org-files-you-already-have">Adapting it to org files you already have</h2>
 67<p>You do not need <code class="verbatim">init</code>, a config file, or templates. Every command takes the same two paths:</p>
 68<pre><code class="language-sh highlight"><span class="source shell bash"><span class="meta function-call shell"><span class="variable function shell">orgo</span></span><span class="meta function-call arguments shell"> serve <span class="keyword operator assignment redirection shell">&lt;</span>SOURCE<span class="keyword operator assignment redirection shell">&gt;</span> <span class="punctuation terminator file-descriptor shell">-</span>o <span class="keyword operator assignment redirection shell">&lt;</span>OUTPUT<span class="keyword operator assignment redirection shell">&gt;</span></span></span></code></pre>
 69<h3 id="source-is-the-url-root">SOURCE is the URL root</h3>
 70<p>This is the one thing worth getting right, and it is not "the project directory" — it is <strong>the directory whose contents should sit at the top of your site</strong>. A file at <code class="verbatim">SOURCE/blog/post.org</code> is published at <code class="verbatim">/blog/post.html</code>.</p>
 71<p>So if your writing lives in a <code class="verbatim">content/</code> subdirectory, point at <code class="verbatim">content/</code>, not at the repository around it:</p>
 72<pre><code class="language-sh highlight"><span class="source shell bash"><span class="meta function-call shell"><span class="support function cd shell">cd</span></span><span class="meta function-call arguments shell"> <span class="meta group expansion tilde"><span class="variable language tilde shell">~</span></span>/my-site</span>
 73<span class="meta function-call shell"><span class="variable function shell">orgo</span></span><span class="meta function-call arguments shell"> serve content<span class="variable parameter option shell"><span class="punctuation definition parameter shell"> -</span>o</span> _site        <span class="comment line number-sign shell"><span class="punctuation definition comment begin shell">#</span></span><span class="comment line number-sign shell"> → /blog/post.html</span></span></span></code></pre>
 74<p>Pointing one level too high still builds, which is what makes it worth saying out loud. It just builds the wrong site:</p>
 75<pre><code class="language-sh highlight"><span class="source shell bash"><span class="meta function-call shell"><span class="variable function shell">orgo</span></span><span class="meta function-call arguments shell"> serve .<span class="variable parameter option shell"><span class="punctuation definition parameter shell"> -</span>o</span> _site              <span class="comment line number-sign shell"><span class="punctuation definition comment begin shell">#</span></span><span class="comment line number-sign shell"> → /content/blog/post.html</span></span></span></code></pre>
 76<p>Every URL gains a <code class="verbatim">/content/</code> prefix, and every non-org file in the repository — <code class="verbatim">README.md</code>, build scripts, licence files — is copied into the output as a site asset. If you see either symptom, you picked the directory above the one you meant.</p>
 77<h3 id="common-layouts">Common layouts</h3>
 78<table>
 79<thead>
 80<tr><th>Your files</th><th>Command</th></tr>
 81</thead>
 82<tbody>
 83<tr><td><code class="verbatim">~/notes/*.org</code></td><td><code class="verbatim">orgo serve ~/notes -o /tmp/notes-site</code></td></tr>
 84<tr><td><code class="verbatim">my-site/content/**/*.org</code></td><td><code class="verbatim">cd my-site &amp;&amp; orgo serve content -o _site</code></td></tr>
 85<tr><td><code class="verbatim">my-site/*.org</code> at the top level</td><td><code class="verbatim">cd my-site &amp;&amp; orgo serve . -o _site</code></td></tr>
 86<tr><td>Org files scattered in a code repo</td><td>Do not. Copy or symlink the ones you publish into one directory.</td></tr>
 87</tbody>
 88</table>
 89<h3 id="output-can-live-inside-the-source">OUTPUT can live inside the source</h3>
 90<p><code class="verbatim">orgo serve . -o _site</code> is fine: the output directory is recognised and skipped, so the build never copies its own output back into itself. Nothing dot-prefixed is published either, so <code class="verbatim">.git</code> stays out of a site built from a repository root.</p>
 91<h3 id="where-config-and-templates-go">Where config and templates go</h3>
 92<p>Both live in the <strong>source</strong> directory — <code class="verbatim">SOURCE/orgo.toml</code> and <code class="verbatim">SOURCE/templates/</code> — and neither is published. If you would rather keep the config elsewhere, name it:</p>
 93<pre><code class="language-sh highlight"><span class="source shell bash"><span class="meta function-call shell"><span class="variable function shell">orgo</span></span><span class="meta function-call arguments shell"> serve content<span class="variable parameter option shell"><span class="punctuation definition parameter shell"> -</span>o</span> _site<span class="variable parameter option shell"><span class="punctuation definition parameter shell"> --</span>config</span> config/orgo.toml</span></span></code></pre>
 94<h3 id="a-worked-example">A worked example</h3>
 95<p>A repository laid out as <code class="verbatim">content/</code> (org files), <code class="verbatim">theme/</code> (unrelated), <code class="verbatim">build.py</code>:</p>
 96<pre><code class="language-sh highlight"><span class="source shell bash"><span class="meta function-call shell"><span class="support function cd shell">cd</span></span><span class="meta function-call arguments shell"> <span class="meta group expansion tilde"><span class="variable language tilde shell">~</span></span>/my-site</span>
 97
 98<span class="comment line number-sign shell"><span class="punctuation definition comment begin shell">#</span></span><span class="comment line number-sign shell"> What is actually in there, before trusting anything with it.</span><span class="comment line number-sign shell">
 99</span><span class="meta function-call shell"><span class="variable function shell">orgo</span></span><span class="meta function-call arguments shell"> audit content</span>
100
101<span class="comment line number-sign shell"><span class="punctuation definition comment begin shell">#</span></span><span class="comment line number-sign shell"> Build it somewhere disposable and look.</span><span class="comment line number-sign shell">
102</span><span class="meta function-call shell"><span class="variable function shell">orgo</span></span><span class="meta function-call arguments shell"> serve content<span class="variable parameter option shell"><span class="punctuation definition parameter shell"> -</span>o</span> /tmp/preview</span>
103
104<span class="comment line number-sign shell"><span class="punctuation definition comment begin shell">#</span></span><span class="comment line number-sign shell"> Happy with it? Build for real, failing on broken links.</span><span class="comment line number-sign shell">
105</span><span class="meta function-call shell"><span class="variable function shell">orgo</span></span><span class="meta function-call arguments shell"> build content<span class="variable parameter option shell"><span class="punctuation definition parameter shell"> -</span>o</span> _site<span class="variable parameter option shell"><span class="punctuation definition parameter shell"> --</span>strict</span></span></span></code></pre>
106<p>The audit reports which org constructs appear, how often, and whether each is supported — names, counts and line numbers only, never your text. See <a href="guide/09-auditing.html">Auditing a corpus</a>.</p>
107<p>Nothing in your files has to change. With no config you get a complete site: a built-in layout, navigation across your top-level pages, and syntax highlighting.</p>
108<h2 id="write-a-page">Write a page</h2>
109<p>Any <code class="verbatim">.org</code> file under the source directory becomes a page at the matching path. <code class="verbatim">notes/rust/borrowing.org</code> becomes <code class="verbatim">notes/rust/borrowing.html</code>.</p>
110<pre><code class="language-org highlight"><span class="text org"><span class="keyword other keyword org">#+TITLE:</span><span class="string unquoted org"> Borrowing</span>
111<span class="keyword other keyword org">#+DATE:</span><span class="string unquoted org"> &lt;2026-02-02 Mon&gt;</span>
112<span class="keyword other keyword org">#+FILETAGS:</span><span class="string unquoted org"> :rust:notes:</span>
113<span class="keyword other keyword org">#+DESCRIPTION:</span><span class="string unquoted org"> How the borrow checker thinks about lifetimes.</span>
114
115An opening paragraph, which becomes the excerpt in listings when there is no
116description.
117
118<span class="markup heading org"><span class="punctuation definition heading org">*</span> A heading
119</span>
120Ordinary org: <span class="markup bold org">*bold*</span>, <span class="markup italic org">/italic/</span>, <span class="markup raw inline org">~code~</span>, <span class="punctuation definition link org">[[</span><span class="markup underline link org">https://orgmode.org</span><span class="punctuation definition link org">]</span><span class="punctuation definition link org">[</span><span class="string other link title org">links</span><span class="punctuation definition link org">]]</span>, and lists.
121
122<span class="markup raw block org"><span class="keyword control block begin org">#+BEGIN_SRC</span><span class="variable parameter org"> rust</span>
123fn main() {}
124<span class="keyword control block end org">#+END_SRC</span></span></span></code></pre>
125<p>The keywords are all optional. <code class="verbatim">#+TITLE:</code> names the page, <code class="verbatim">#+DATE:</code> orders it in listings, <code class="verbatim">#+FILETAGS:</code> groups it on tag pages, and <code class="verbatim">#+DESCRIPTION:</code> is its summary.</p>
126<h3 id="control-the-url">Control the URL</h3>
127<p>By default the filename decides the URL. <code class="verbatim">#+SLUG:</code> overrides it, which is how a date-prefixed filename becomes a clean address:</p>
128<pre><code class="language-org highlight"><span class="text org"><span class="keyword other keyword org">#+TITLE:</span><span class="string unquoted org"> Borrowing</span>
129<span class="keyword other keyword org">#+SLUG:</span><span class="string unquoted org"> borrowing-explained</span></span></code></pre>
130<p><code class="verbatim">2026-02-02-borrowing.org</code> now publishes as <code class="verbatim">borrowing-explained.html</code>.</p>
131<h3 id="keep-something-unfinished-out-of-the-build">Keep something unfinished out of the build</h3>
132<pre><code class="language-org highlight"><span class="text org"><span class="keyword other keyword org">#+DRAFT:</span><span class="string unquoted org"> t</span></span></code></pre>
133<p>The page is not written, and does not appear in listings or navigation. Preview it while you work with <code class="verbatim">--drafts</code>:</p>
134<pre><code class="language-sh highlight"><span class="source shell bash"><span class="meta function-call shell"><span class="variable function shell">orgo</span></span><span class="meta function-call arguments shell"> serve my-site<span class="variable parameter option shell"><span class="punctuation definition parameter shell"> -</span>o</span> _site<span class="variable parameter option shell"><span class="punctuation definition parameter shell"> --</span>drafts</span></span></span></code></pre>
135<h2 id="change-the-design">Change the design</h2>
136<p>Everything visual lives in <code class="verbatim">templates/base.html</code>. It is an ordinary <a href="https://docs.rs/minijinja">minijinja</a> (Jinja2) template, and replacing it replaces the whole layout:</p>
137<pre><code class="language-html highlight"><span class="text html basic"><span class="meta tag sgml html"><span class="punctuation definition tag html">&lt;!</span><span class="meta tag sgml doctype html"><span class="entity name tag doctype html">DOCTYPE</span> html</span><span class="punctuation definition tag html">&gt;</span></span>
138<span class="meta tag structure any html"><span class="punctuation definition tag begin html">&lt;</span><span class="entity name tag structure any html">html</span> <span class="meta attribute-with-value html"><span class="entity other attribute-name html">lang</span><span class="punctuation separator key-value html">=</span></span><span class="meta attribute-with-value html"><span class="string quoted double html"><span class="punctuation definition string begin html">&quot;</span>{{ site.language }}<span class="punctuation definition string end html">&quot;</span></span></span><span class="punctuation definition tag end html">&gt;</span></span>
139<span class="meta tag structure any html"><span class="punctuation definition tag begin html">&lt;</span><span class="entity name tag structure any html">head</span><span class="punctuation definition tag end html">&gt;</span></span>
140  <span class="meta tag inline any html"><span class="punctuation definition tag begin html">&lt;</span><span class="entity name tag inline any html">meta</span> <span class="meta attribute-with-value html"><span class="entity other attribute-name html">charset</span><span class="punctuation separator key-value html">=</span></span><span class="meta attribute-with-value html"><span class="string quoted double html"><span class="punctuation definition string begin html">&quot;</span>utf-8<span class="punctuation definition string end html">&quot;</span></span></span><span class="punctuation definition tag end html">&gt;</span></span>
141  <span class="meta tag inline any html"><span class="punctuation definition tag begin html">&lt;</span><span class="entity name tag inline any html">title</span><span class="punctuation definition tag end html">&gt;</span></span>{{ page.title }} — {{ site.title }}<span class="meta tag inline any html"><span class="punctuation definition tag begin html">&lt;/</span><span class="entity name tag inline any html">title</span><span class="punctuation definition tag end html">&gt;</span></span>
142  <span class="meta tag inline any html"><span class="punctuation definition tag begin html">&lt;</span><span class="entity name tag inline any html">link</span> <span class="meta attribute-with-value html"><span class="entity other attribute-name html">rel</span><span class="punctuation separator key-value html">=</span></span><span class="meta attribute-with-value html"><span class="string quoted double html"><span class="punctuation definition string begin html">&quot;</span>stylesheet<span class="punctuation definition string end html">&quot;</span></span></span> <span class="meta attribute-with-value html"><span class="entity other attribute-name html">href</span><span class="punctuation separator key-value html">=</span></span><span class="meta attribute-with-value html"><span class="string quoted double html"><span class="punctuation definition string begin html">&quot;</span>{{ root }}style.css<span class="punctuation definition string end html">&quot;</span></span></span><span class="punctuation definition tag end html">&gt;</span></span>
143<span class="meta tag structure any html"><span class="punctuation definition tag begin html">&lt;/</span><span class="entity name tag structure any html">head</span><span class="punctuation definition tag end html">&gt;</span></span>
144<span class="meta tag structure any html"><span class="punctuation definition tag begin html">&lt;</span><span class="entity name tag structure any html">body</span><span class="punctuation definition tag end html">&gt;</span></span>
145  <span class="meta tag block any html"><span class="punctuation definition tag begin html">&lt;</span><span class="entity name tag block any html">nav</span><span class="punctuation definition tag end html">&gt;</span></span>{% for item in nav %}<span class="meta tag inline a html"><span class="punctuation definition tag begin html">&lt;</span><span class="entity name tag inline a html">a</span> <span class="meta attribute-with-value html"><span class="entity other attribute-name html">href</span><span class="punctuation separator key-value html">=</span></span><span class="meta attribute-with-value html"><span class="string quoted double html"><span class="punctuation definition string begin html">&quot;</span>{{ item.url }}<span class="punctuation definition string end html">&quot;</span></span></span><span class="punctuation definition tag end html">&gt;</span></span>{{ item.title }}<span class="meta tag inline a html"><span class="punctuation definition tag begin html">&lt;/</span><span class="entity name tag inline a html">a</span><span class="punctuation definition tag end html">&gt;</span></span>{% endfor %}<span class="meta tag block any html"><span class="punctuation definition tag begin html">&lt;/</span><span class="entity name tag block any html">nav</span><span class="punctuation definition tag end html">&gt;</span></span>
146  <span class="meta tag block any html"><span class="punctuation definition tag begin html">&lt;</span><span class="entity name tag block any html">h1</span><span class="punctuation definition tag end html">&gt;</span></span>{{ page.title }}<span class="meta tag block any html"><span class="punctuation definition tag begin html">&lt;/</span><span class="entity name tag block any html">h1</span><span class="punctuation definition tag end html">&gt;</span></span>
147  {{ body | safe }}
148<span class="meta tag structure any html"><span class="punctuation definition tag begin html">&lt;/</span><span class="entity name tag structure any html">body</span><span class="punctuation definition tag end html">&gt;</span></span>
149<span class="meta tag structure any html"><span class="punctuation definition tag begin html">&lt;/</span><span class="entity name tag structure any html">html</span><span class="punctuation definition tag end html">&gt;</span></span></span></code></pre>
150<p><code class="verbatim">root</code> is the <code class="verbatim">../</code> prefix back to the site root, so the same template works at any depth. Any other file in the source directory — <code class="verbatim">style.css</code>, images, fonts — is copied to the output untouched.</p>
151<p>Editing a template rebuilds every page that uses it, so the browser reloads while you are still looking at it. The full list of variables is in <a href="guide/04-templates.html">Templates</a>.</p>
152<h2 id="add-a-blog-index">Add a blog index</h2>
153<p>Listing pages have no source file; they are declared in <code class="verbatim">orgo.toml</code>:</p>
154<pre><code class="language-toml highlight"><span class="source toml"><span class="punctuation definition table array toml">[[</span><span class="entity name section toml">collections</span><span class="punctuation definition table array toml">]]</span>
155<span class="variable other key toml">source</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>
156<span class="variable other key toml">output</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>
157<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>list.html<span class="punctuation definition string end toml">&quot;</span></span>
158<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>Blog<span class="punctuation definition string end toml">&quot;</span></span>
159<span class="variable other key toml">sort</span> <span class="keyword operator assignment toml">=</span> <span class="string quoted double toml"><span class="punctuation definition string begin toml">&quot;</span>date<span class="punctuation definition string end toml">&quot;</span></span>
160<span class="variable other key toml">order</span> <span class="keyword operator assignment toml">=</span> <span class="string quoted double toml"><span class="punctuation definition string begin toml">&quot;</span>desc<span class="punctuation definition string end toml">&quot;</span></span>
161<span class="variable other key toml">nav</span> <span class="keyword operator assignment toml">=</span> <span class="constant language toml">true</span></span></code></pre>
162<p>That is also how you get tag pages, pagination and an RSS feed — same mechanism, more settings. See <a href="guide/03-collections.html">Collections</a>.</p>
163<h2 id="build-for-real">Build for real</h2>
164<pre><code class="language-sh highlight"><span class="source shell bash"><span class="meta function-call shell"><span class="variable function shell">orgo</span></span><span class="meta function-call arguments shell"> build my-site<span class="variable parameter option shell"><span class="punctuation definition parameter shell"> -</span>o</span> _site<span class="variable parameter option shell"><span class="punctuation definition parameter shell"> --</span>strict</span></span></span></code></pre>
165<p><code class="verbatim">--strict</code> turns broken internal links and parse diagnostics into a non-zero exit, which is what you want in CI. Deployment is just copying <code class="verbatim">_site</code> somewhere; see <a href="guide/10-deploying.html">Deploying</a>.</p>
166<h2 id="next">Next</h2>
167<ul>
168<li><a href="guide/01-cli.html">Command reference</a> — every command and flag.</li>
169<li><a href="guide/02-configuration.html">Configuration</a> — every setting in <code class="verbatim">orgo.toml</code>.</li>
170<li><a href="guide/05-org-support.html">Org support</a> — exactly which org syntax is handled.</li>
171</ul>
172</main>
173<footer class="site">
174Built with orgo &mdash; these docs are an orgo site.
175</footer>
176</body>
177</html>