3d17b4a205 · cmc/cleberg.net

1

#+date: [2026-08-11 Tue 20:51:00]

2

#+title: I Built My Own Org-Mode Static Site Generator

3

#+description: I was tired of bolting solutions onto my SSGs, so I built my own.

4

#+slug: orgo

5

#+filetags: :development:org-mode:

6

7

* Introducing: Orgo

8

9

For a long time, I've been using [[https://github.com/emacs-love/weblorg][weblorg]], a static site generator (SSG) for

10

org-mode. It uses Emacs Lisp, which pairs well with Emacs. However, it has a few

11

downsides:

12

13

- since it requires Emacs, the set-up and maintenance is heavy

14

- it has upstream dependencies that must also be installed and loaded into Emacs

15

- it re-runs the full process every time you need to regenerate the site, even

16

if you only change a single character in one file

17

- since it runs through Emacs in the background, it takes quite a while to build

18

my site (~180 pages)

19

20

So, I decided to spin up my own org-mode-based SSG: [[https://github.com/krazywarez/orgo][orgo]]. This SSG uses org-mode

21

(rather than markdown) for its content.

22

23

#+caption: The orgo CLI

24

#+attr_html: :alt Terminal output of orgo --help, listing the build, watch, serve, clean, audit, and init commands.

25

[[https://img.cleberg.net/blog/20260811-orgo/orgo.webp]]

26

27

* Results Up Front

28

29

I want to highlight the speed first, before I go into the major differences. As

30

you can see in the table below, orgo is incredibly fast.

31

32

| Method | Time | Diff |

33

|----------------------------------------+-------+-------------|

34

| weblorg (=emacs --script publish.el=) | 49.0s | |

35

| weblorg + [[https://github.com/ccleberg/cleberg.net/blob/8ec9cdfeae71068a8924dd9f61b9cc28c947ec31/build.py][build.py]]                     | 50.3s |             |

36

| orgo, cold build | *0.22s* | 223× faster |

37

| orgo, nothing changed since last build | *0.13s* | 377× faster |

38

39

Additionally, I added a few new features that weblorg didn't provide me:

40

41

- Native features I used to build in Python post-weblorg:

42

- Tag listings

43

- Year separators on the blog page

44

- RSS feed

45

- Sitemap

46

- Recent posts lists

47

- Syntax highlighting for 75 languages is supported, and you can drop in your

48

own syntax definitions for anything missing.

49

- Builds are incremental. Only the pages whose content, config, or templates

50

changed get re-rendered — adding a single post re-renders that post and the

51

index that lists it, and nothing else.

52

- There is no Emacs, no package manager, and no runtime to install since orgo is

53

a single binary.

54

55

This results in a fast, clean, and simple SSG that stays out of my way instead

56

of requiring extensive set-up and maintenance.

57

58

* What It Is Built On

59

60

/Note: This section is for the nerds. Feel free to skip if you don't care about

61

the technology behind orgo./

62

63

orgo is Rust, and it leans on a handful of well-worn crates rather than

64

reinventing them:

65

66

- The org parser is hand-written, about 1,500 lines of it. There is no org-mode

67

crate to lean on, and writing that parser is most of what writing an org SSG

68

turns out to be.

69

- Templates run on [[https://crates.io/crates/minijinja][minijinja]], which speaks Jinja2. weblorg's templates are

70

written for templatel, which is close enough that porting them was mostly a

71

rename job.

72

- Syntax highlighting is [[https://crates.io/crates/syntect][syntect]], so the definitions and the themes are Sublime

73

Text's. This site renders code with =InspiredGitHub=.

74

- Incremental builds hash the content, the config, and the templates with

75

  [[https://crates.io/crates/blake3][blake3]]. A page is re-rendered when its hash changes, and the manifest that

76

remembers them is JSON sitting in the output directory.

77

- Pages render in parallel with [[https://crates.io/crates/rayon][rayon]], which is straightforward here because

78

each page writes only its own file.

79

- 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

80

  edits with a [[https://crates.io/crates/tiny_http][tiny_http]] server in front of the output.

81

82

* Getting Started

83

84

If you use org-mode (or have been looking for a proper org-mode SSG), check it

85

out and let me know what you think.

86

87

It's as simple as installing, initializing a new site, and serving it!

88

89

#+begin_src shell

90

cargo install orgo

91

orgo init my-site

92

orgo serve my-site -o _site

93

#+end_src

94

95

It can create a new project for you, adapt to your current org site, or simply

96

serve your folder of org-mode notes and files.

97

98

Three more commands cover the rest of the day-to-day:

99

100

- =orgo watch= rebuilds incrementally as files change, driven by filesystem

101

events, without serving anything. This is handy when something else is already

102

serving the output directory.

103

- =orgo clean= removes the output directory, cache manifest and all, for when you

104

want to start from scratch.

105

- =orgo audit= reports which org constructs a folder actually uses, and marks the

106

ones it doesn't handle.

107

108

#+caption: An orgo Audit Report

109

#+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.

110

[[https://img.cleberg.net/blog/20260811-orgo/audit.webp]]

111

112

* The Future

113

114

I'll be looking into making some built-in themes soon and exploring other

115

features that make it a bit more seamless, as well as adopting to various

116

methods different users may expect it to work.

117

118

If you have any suggestions, reach out and let me know or open an issue/PR on

119

GitHub!

@@ -0,0 +1,119 @@
	1	#+date: [2026-08-11 Tue 20:51:00]
	2	#+title: I Built My Own Org-Mode Static Site Generator
	3	#+description: I was tired of bolting solutions onto my SSGs, so I built my own.
	4	#+slug: orgo
	5	#+filetags: :development:org-mode:
	6
	7	* Introducing: Orgo
	8
	9	For a long time, I've been using [[https://github.com/emacs-love/weblorg][weblorg]], a static site generator (SSG) for
	10	org-mode. It uses Emacs Lisp, which pairs well with Emacs. However, it has a few
	11	downsides:
	12
	13	- since it requires Emacs, the set-up and maintenance is heavy
	14	- it has upstream dependencies that must also be installed and loaded into Emacs
	15	- it re-runs the full process every time you need to regenerate the site, even
	16	if you only change a single character in one file
	17	- since it runs through Emacs in the background, it takes quite a while to build
	18	my site (~180 pages)
	19
	20	So, I decided to spin up my own org-mode-based SSG: [[https://github.com/krazywarez/orgo][orgo]]. This SSG uses org-mode
	21	(rather than markdown) for its content.
	22
	23	#+caption: The orgo CLI
	24	#+attr_html: :alt Terminal output of orgo --help, listing the build, watch, serve, clean, audit, and init commands.
	25	[[https://img.cleberg.net/blog/20260811-orgo/orgo.webp]]
	26
	27	* Results Up Front
	28
	29	I want to highlight the speed first, before I go into the major differences. As
	30	you can see in the table below, orgo is incredibly fast.
	31
	32	\| Method \| Time \| Diff \|
	33	\|----------------------------------------+-------+-------------\|
	34	\| weblorg (=emacs --script publish.el=) \| 49.0s \| \|
	35	\| weblorg + [[https://github.com/ccleberg/cleberg.net/blob/8ec9cdfeae71068a8924dd9f61b9cc28c947ec31/build.py][build.py]] \| 50.3s \| \|
	36	\| orgo, cold build \| 0.22s \| 223× faster \|
	37	\| orgo, nothing changed since last build \| 0.13s \| 377× faster \|
	38
	39	Additionally, I added a few new features that weblorg didn't provide me:
	40
	41	- Native features I used to build in Python post-weblorg:
	42	- Tag listings
	43	- Year separators on the blog page
	44	- RSS feed
	45	- Sitemap
	46	- Recent posts lists
	47	- Syntax highlighting for 75 languages is supported, and you can drop in your
	48	own syntax definitions for anything missing.
	49	- Builds are incremental. Only the pages whose content, config, or templates
	50	changed get re-rendered — adding a single post re-renders that post and the
	51	index that lists it, and nothing else.
	52	- There is no Emacs, no package manager, and no runtime to install since orgo is
	53	a single binary.
	54
	55	This results in a fast, clean, and simple SSG that stays out of my way instead
	56	of requiring extensive set-up and maintenance.
	57
	58	* What It Is Built On
	59
	60	/Note: This section is for the nerds. Feel free to skip if you don't care about
	61	the technology behind orgo./
	62
	63	orgo is Rust, and it leans on a handful of well-worn crates rather than
	64	reinventing them:
	65
	66	- The org parser is hand-written, about 1,500 lines of it. There is no org-mode
	67	crate to lean on, and writing that parser is most of what writing an org SSG
	68	turns out to be.
	69	- Templates run on [[https://crates.io/crates/minijinja][minijinja]], which speaks Jinja2. weblorg's templates are
	70	written for templatel, which is close enough that porting them was mostly a
	71	rename job.
	72	- Syntax highlighting is [[https://crates.io/crates/syntect][syntect]], so the definitions and the themes are Sublime
	73	Text's. This site renders code with =InspiredGitHub=.
	74	- Incremental builds hash the content, the config, and the templates with
	75	[[https://crates.io/crates/blake3][blake3]]. A page is re-rendered when its hash changes, and the manifest that
	76	remembers them is JSON sitting in the output directory.
	77	- Pages render in parallel with [[https://crates.io/crates/rayon][rayon]], which is straightforward here because
	78	each page writes only its own file.
	79	- 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
	80	edits with a [[https://crates.io/crates/tiny_http][tiny_http]] server in front of the output.
	81
	82	* Getting Started
	83
	84	If you use org-mode (or have been looking for a proper org-mode SSG), check it
	85	out and let me know what you think.
	86
	87	It's as simple as installing, initializing a new site, and serving it!
	88
	89	#+begin_src shell
	90	cargo install orgo
	91	orgo init my-site
	92	orgo serve my-site -o _site
	93	#+end_src
	94
	95	It can create a new project for you, adapt to your current org site, or simply
	96	serve your folder of org-mode notes and files.
	97
	98	Three more commands cover the rest of the day-to-day:
	99
	100	- =orgo watch= rebuilds incrementally as files change, driven by filesystem
	101	events, without serving anything. This is handy when something else is already
	102	serving the output directory.
	103	- =orgo clean= removes the output directory, cache manifest and all, for when you
	104	want to start from scratch.
	105	- =orgo audit= reports which org constructs a folder actually uses, and marks the
	106	ones it doesn't handle.
	107
	108	#+caption: An orgo Audit Report
	109	#+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.
	110	[[https://img.cleberg.net/blog/20260811-orgo/audit.webp]]
	111
	112	* The Future
	113
	114	I'll be looking into making some built-in themes soon and exploring other
	115	features that make it a bit more seamless, as well as adopting to various
	116	methods different users may expect it to work.
	117
	118	If you have any suggestions, reach out and let me know or open an issue/PR on
	119	GitHub!

Commit 3d17b4a205

Commit `3d17b4a205`