publish new post: orgoHEADmain

1 files changed, 119 insertions, 0 deletions

diff --git a/content/blog/2026-08-11-orgo.org b/content/blog/2026-08-11-orgo.org
new file mode 100644
index 0000000..9204fc5
--- /dev/null
+++ b/content/blog/2026-08-11-orgo.org
@@ -0,0 +1,119 @@
+#+date: [2026-08-11 Tue 20:51:00]
+#+title: I Built My Own Org-Mode Static Site Generator
+#+description: I was tired of bolting solutions onto my SSGs, so I built my own.
+#+slug: orgo
+#+filetags: :development:org-mode:
+
+* Introducing: Orgo
+
+For a long time, I've been using [[https://github.com/emacs-love/weblorg][weblorg]], a static site generator (SSG) for
+org-mode. It uses Emacs Lisp, which pairs well with Emacs. However, it has a few
+downsides:
+
+- since it requires Emacs, the set-up and maintenance is heavy
+- it has upstream dependencies that must also be installed and loaded into Emacs
+- it re-runs the full process every time you need to regenerate the site, even
+  if you only change a single character in one file
+- since it runs through Emacs in the background, it takes quite a while to build
+  my site (~180 pages)
+
+So, I decided to spin up my own org-mode-based SSG: [[https://github.com/krazywarez/orgo][orgo]]. This SSG uses org-mode
+(rather than markdown) for its content.
+
+#+caption: The orgo CLI
+#+attr_html: :alt Terminal output of orgo --help, listing the build, watch, serve, clean, audit, and init commands.
+[[https://img.cleberg.net/blog/20260811-orgo/orgo.webp]]
+
+* Results Up Front
+
+I want to highlight the speed first, before I go into the major differences. As
+you can see in the table below, orgo is incredibly fast.
+
+| Method                                 | Time  | Diff        |
+|----------------------------------------+-------+-------------|
+| weblorg (=emacs --script publish.el=)    | 49.0s |             |
+| weblorg + [[https://github.com/ccleberg/cleberg.net/blob/8ec9cdfeae71068a8924dd9f61b9cc28c947ec31/build.py][build.py]]                     | 50.3s |             |
+| orgo, cold build                       | *0.22s* | 223× faster |
+| orgo, nothing changed since last build | *0.13s* | 377× faster |
+
+Additionally, I added a few new features that weblorg didn't provide me:
+
+- Native features I used to build in Python post-weblorg:
+  - Tag listings
+  - Year separators on the blog page
+  - RSS feed
+  - Sitemap
+  - Recent posts lists
+- Syntax highlighting for 75 languages is supported, and you can drop in your
+  own syntax definitions for anything missing.
+- Builds are incremental. Only the pages whose content, config, or templates
+  changed get re-rendered — adding a single post re-renders that post and the
+  index that lists it, and nothing else.
+- There is no Emacs, no package manager, and no runtime to install since orgo is
+  a single binary.
+
+This results in a fast, clean, and simple SSG that stays out of my way instead
+of requiring extensive set-up and maintenance.
+
+* What It Is Built On
+
+/Note: This section is for the nerds. Feel free to skip if you don't care about
+the technology behind orgo./
+
+orgo is Rust, and it leans on a handful of well-worn crates rather than
+reinventing them:
+
+- The org parser is hand-written, about 1,500 lines of it. There is no org-mode
+  crate to lean on, and writing that parser is most of what writing an org SSG
+  turns out to be.
+- Templates run on [[https://crates.io/crates/minijinja][minijinja]], which speaks Jinja2. weblorg's templates are
+  written for templatel, which is close enough that porting them was mostly a
+  rename job.
+- Syntax highlighting is [[https://crates.io/crates/syntect][syntect]], so the definitions and the themes are Sublime
+  Text's. This site renders code with =InspiredGitHub=.
+- Incremental builds hash the content, the config, and the templates with
+  [[https://crates.io/crates/blake3][blake3]]. A page is re-rendered when its hash changes, and the manifest that
+  remembers them is JSON sitting in the output directory.
+- Pages render in parallel with [[https://crates.io/crates/rayon][rayon]], which is straightforward here because
+  each page writes only its own file.
+- The config is TOML, the CLI is [[https://crates.io/crates/clap][clap]], and =orgo serve= is [[https://crates.io/crates/notify][notify]] watching for
+  edits with a [[https://crates.io/crates/tiny_http][tiny_http]] server in front of the output.
+
+* Getting Started
+
+If you use org-mode (or have been looking for a proper org-mode SSG), check it
+out and let me know what you think.
+
+It's as simple as installing, initializing a new site, and serving it!
+
+#+begin_src shell
+cargo install orgo
+orgo init my-site
+orgo serve my-site -o _site
+#+end_src
+
+It can create a new project for you, adapt to your current org site, or simply
+serve your folder of org-mode notes and files.
+
+Three more commands cover the rest of the day-to-day:
+
+- =orgo watch= rebuilds incrementally as files change, driven by filesystem
+  events, without serving anything. This is handy when something else is already
+  serving the output directory.
+- =orgo clean= removes the output directory, cache manifest and all, for when you
+  want to start from scratch.
+- =orgo audit= reports which org constructs a folder actually uses, and marks the
+  ones it doesn't handle.
+
+#+caption: An orgo Audit Report
+#+attr_html: :alt Terminal output of orgo audit, tallying every org construct in a corpus by frequency and marking each one in or out of scope, followed by counts of keywords, block types, drawers, and link schemes.
+[[https://img.cleberg.net/blog/20260811-orgo/audit.webp]]
+
+* The Future
+
+I'll be looking into making some built-in themes soon and exploring other
+features that make it a bit more seamless, as well as adopting to various
+methods different users may expect it to work.
+
+If you have any suggestions, reach out and let me know or open an issue/PR on
+GitHub!