Commit `51d965d2ef`

51d965d2ef7e562f8b1efbcd8da7734304ded031

parent: 8844e2b788

Unsigned

cmc <hello@cleberg.net> · 2026-08-11 22:42 UTC

README goes back to markdown

crates.io renders the readme as markdown whatever the extension, so an org file
would have shown its own markup literally on the crate page — the one place the
README is read by people deciding whether to try this at all.

Same content, hand-written rather than converted, which also let the two tables
gain the header rows markdown needs. CHANGELOG and RELEASING stay org; they are
read here, where GitHub renders org fine.

`readme` in Cargo.toml and the release tarball follow it back.

Layout: unified · split

.github/workflows/release.yml +1 −1

		@@ -77,7 +77,7 @@ jobs:
77	77	staging="orgo-${{ github.event.inputs.tag \|\| github.ref_name }}-${{ matrix.target }}"
78	78	mkdir "$staging"
79	79	cp "target/${{ matrix.target }}/release/orgo" "$staging/"
80		cp README.org LICENSE "$staging/"
	80	cp README.md LICENSE "$staging/"
81	81	tar czf "$staging.tar.gz" "$staging"
82	82	shasum -a 256 "$staging.tar.gz" > "$staging.tar.gz.sha256"
83	83

Cargo.toml +1 −1

		@@ -4,7 +4,7 @@ version = "0.19.1"
4	4	edition = "2021"
5	5	description = "Org-mode static site generator that renders the org element tree straight to HTML"
6	6	license = "0BSD"
7		readme = "README.org"
	7	readme = "README.md"
8	8	keywords = ["org-mode", "static-site-generator", "emacs", "html", "blog"]
9	9	categories = ["command-line-utilities", "text-processing"]
10	10	repository = "https://github.com/ccleberg/orgo"

README.md added +111

		@@ -0,0 +1,111 @@
	1	# orgo
	2
	3	Turn a folder of org files into a website.
	4
	5	You write posts the way you already do — an `.org` file per page, in whatever directory
	6	structure suits you — and orgo builds a complete site from them: pages, navigation, a blog
	7	index, tags, an RSS feed, syntax-highlighted code. It is one binary with nothing to
	8	install alongside it, and you do not need Emacs to build your site, only to write in a
	9	format Emacs made.
	10
	11	Org is the source language here, not something to convert away from first. Tools that
	12	route org through markdown lose what markdown has no words for — property drawers, a
	13	heading's TODO state and tags, `#+` keywords, ID links, captions on images. orgo keeps all
	14	of it, and its output is checked page by page against what Emacs' own exporter produces
	15	from the same file.
	16
	17	Documentation: <https://ccleberg.github.io/orgo/> — that site is written in org and
	18	built by orgo, so it doubles as the longest worked example available.
	19
	20	## Install
	21
	22	You need [Rust](https://rustup.rs) (1.88 or newer). Nothing else — syntax highlighting and
	23	its themes are compiled in.
	24
	25	```sh
	26	git clone https://github.com/ccleberg/orgo
	27	cd orgo
	28	cargo install --path .
	29	```
	30
	31	That puts an `orgo` command on your `PATH`. Full notes, including how to run it without
	32	installing anything: <https://ccleberg.github.io/orgo/install.html>
	33
	34	## Your first site
	35
	36	```sh
	37	orgo init my-site
	38	orgo serve my-site -o _site
	39	```
	40
	41	Open <http://127.0.0.1:3000>. Edit `my-site/index.org`, save, and the page reloads on its
	42	own — that is the loop you will spend your time in.
	43
	44	`init` writes a starter post, a page layout you can edit, and a config file with every
	45	setting explained in comments. It never overwrites a file you already have.
	46
	47	## Or point it at writing you already have
	48
	49	```sh
	50	orgo build ~/notes -o _site
	51	```
	52
	53	No config file, no templates, no orgo-specific markup in your files. You get a real site:
	54	every page, links between them resolved, navigation across the top, code highlighted. That
	55	is a supported way to use it rather than a demo — configuration changes what you get, it
	56	is never what makes it work.
	57
	58	Nothing that should stay private is published: dot-directories like `.git`, your templates
	59	and the output folder itself are all skipped.
	60
	61	Want to know what orgo will make of your files before trusting it with them?
	62	`orgo audit ~/notes` reports which org constructs you use and how each one lands, with
	63	counts and line numbers — never the text of your writing, so the report is safe to share.
	64
	65	## What you can add when you want it
	66
	67	Each of these is a few lines of config, and each has a page in the guide:
	68
	69	\| Add \| Documented in \|
	70	\|---\|---\|
	71	\| A blog index, newest first \| [Collections](https://ccleberg.github.io/orgo/guide/03-collections.html) \|
	72	\| Tag pages, and an index of tags \| [Collections](https://ccleberg.github.io/orgo/guide/03-collections.html) \|
	73	\| An RSS feed \| [Collections](https://ccleberg.github.io/orgo/guide/03-collections.html) \|
	74	\| Numbered pages when a list gets long \| [Collections](https://ccleberg.github.io/orgo/guide/03-collections.html) \|
	75	\| Your own design, in ordinary HTML templates \| [Templates](https://ccleberg.github.io/orgo/guide/04-templates.html) \|
	76	\| Drafts that stay unpublished until you say so \| [Authoring](https://ccleberg.github.io/orgo/guide/06-authoring.html) \|
	77	\| A table of contents on long posts \| [Authoring](https://ccleberg.github.io/orgo/guide/06-authoring.html) \|
	78	\| Clean URLs that survive a renamed file \| [Authoring](https://ccleberg.github.io/orgo/guide/06-authoring.html) \|
	79
	80	Rebuilds only touch the pages that actually changed, so saving a post on a site with
	81	hundreds of them stays instant.
	82
	83	## The documentation
	84
	85	<https://ccleberg.github.io/orgo/>
	86
	87	\| Page \| What is in it \|
	88	\|---\|---\|
	89	\| [Quick start](https://ccleberg.github.io/orgo/quickstart.html) \| A working site in two commands, then your own writing, then your own design. \|
	90	\| [Install](https://ccleberg.github.io/orgo/install.html) \| Getting the binary, and running it without installing anything. \|
	91	\| [Commands](https://ccleberg.github.io/orgo/guide/01-cli.html) \| Every command and flag, and what each is for. \|
	92	\| [Configuration](https://ccleberg.github.io/orgo/guide/02-configuration.html) \| Every setting in `orgo.toml`, what it changes, and what it costs. \|
	93	\| [Collections](https://ccleberg.github.io/orgo/guide/03-collections.html) \| Blog indexes, tag pages, pagination and RSS feeds. \|
	94	\| [Templates](https://ccleberg.github.io/orgo/guide/04-templates.html) \| Layouts, and every variable a template can use. \|
	95	\| [Org support](https://ccleberg.github.io/orgo/guide/05-org-support.html) \| Which org syntax is handled, which is not, and how the rest degrades. \|
	96	\| [Authoring](https://ccleberg.github.io/orgo/guide/06-authoring.html) \| URLs, drafts, excerpts, tables of contents. \|
	97	\| [Incremental builds](https://ccleberg.github.io/orgo/guide/07-incremental.html) \| How it decides what to rebuild. \|
	98	\| [Watching and serving](https://ccleberg.github.io/orgo/guide/08-workflow.html) \| The write-save-see loop. \|
	99	\| [Auditing](https://ccleberg.github.io/orgo/guide/09-auditing.html) \| Reading a corpus before trusting a tool with it. \|
	100	\| [Deploying](https://ccleberg.github.io/orgo/guide/10-deploying.html) \| Producing a production build, and putting it somewhere. \|
	101
	102	## Building from a checkout
	103
	104	```sh
	105	cargo test # includes a differential check against Emacs, when present
	106	cargo run -- serve docs -o docs/_site # read the documentation locally
	107	```
	108
	109	## Licence
	110
	111	[0BSD](LICENSE). Do what you like with it.

README.org deleted −107

		@@ -1,107 +0,0 @@
1		* orgo
2
3		Turn a folder of org files into a website.
4
5		You write posts the way you already do — an =.org= file per page, in whatever directory
6		structure suits you — and orgo builds a complete site from them: pages, navigation, a blog
7		index, tags, an RSS feed, syntax-highlighted code. It is one binary with nothing to
8		install alongside it, and you do not need Emacs to build your site, only to write in a
9		format Emacs made.
10
11		Org is the source language here, not something to convert away from first. Tools that
12		route org through markdown lose what markdown has no words for — property drawers, a
13		heading's TODO state and tags, =#+= keywords, ID links, captions on images. orgo keeps all
14		of it, and its output is checked page by page against what Emacs' own exporter produces
15		from the same file.
16
17		Documentation: https://ccleberg.github.io/orgo/ — that site is written in org and built
18		by orgo, so it doubles as the longest worked example available.
19
20		** Install
21
22		You need [[https://rustup.rs][Rust]] (1.88 or newer). Nothing else — syntax highlighting
23		and its themes are compiled in.
24
25		#+begin_src sh
26		git clone https://github.com/ccleberg/orgo
27		cd orgo
28		cargo install --path .
29		#+end_src
30
31		That puts an =orgo= command on your =PATH=. Full notes, including how to run it without
32		installing anything: https://ccleberg.github.io/orgo/install.html
33
34		** Your first site
35
36		#+begin_src sh
37		orgo init my-site
38		orgo serve my-site -o _site
39		#+end_src
40
41		Open http://127.0.0.1:3000. Edit =my-site/index.org=, save, and the page reloads on its
42		own — that is the loop you will spend your time in.
43
44		=init= writes a starter post, a page layout you can edit, and a config file with every
45		setting explained in comments. It never overwrites a file you already have.
46
47		** Or point it at writing you already have
48
49		#+begin_src sh
50		orgo build ~/notes -o _site
51		#+end_src
52
53		No config file, no templates, no orgo-specific markup in your files. You get a real site:
54		every page, links between them resolved, navigation across the top, code highlighted. That
55		is a supported way to use it rather than a demo — configuration changes what you get, it
56		is never what makes it work.
57
58		Nothing that should stay private is published: dot-directories like =.git=, your templates
59		and the output folder itself are all skipped.
60
61		Want to know what orgo will make of your files before trusting it with them?
62		=orgo audit ~/notes= reports which org constructs you use and how each one lands, with
63		counts and line numbers — never the text of your writing, so the report is safe to share.
64
65		** What you can add when you want it
66
67		Each of these is a few lines of config, and each has a page in the guide:
68
69		\| A blog index, newest first \| [[https://ccleberg.github.io/orgo/guide/03-collections.html][Collections]] \|
70		\| Tag pages, and an index of tags \| [[https://ccleberg.github.io/orgo/guide/03-collections.html][Collections]] \|
71		\| An RSS feed \| [[https://ccleberg.github.io/orgo/guide/03-collections.html][Collections]] \|
72		\| Numbered pages when a list gets long \| [[https://ccleberg.github.io/orgo/guide/03-collections.html][Collections]] \|
73		\| Your own design, in ordinary HTML templates \| [[https://ccleberg.github.io/orgo/guide/04-templates.html][Templates]] \|
74		\| Drafts that stay unpublished until you say so \| [[https://ccleberg.github.io/orgo/guide/06-authoring.html][Authoring]] \|
75		\| A table of contents on long posts \| [[https://ccleberg.github.io/orgo/guide/06-authoring.html][Authoring]] \|
76		\| Clean URLs that survive a renamed file \| [[https://ccleberg.github.io/orgo/guide/06-authoring.html][Authoring]] \|
77
78		Rebuilds only touch the pages that actually changed, so saving a post on a site with
79		hundreds of them stays instant.
80
81		** The documentation
82
83		https://ccleberg.github.io/orgo/
84
85		\| [[https://ccleberg.github.io/orgo/quickstart.html][Quick start]] \| A working site in two commands, then your own writing, then your own design. \|
86		\| [[https://ccleberg.github.io/orgo/install.html][Install]] \| Getting the binary, and running it without installing anything. \|
87		\| [[https://ccleberg.github.io/orgo/guide/01-cli.html][Commands]] \| Every command and flag, and what each is for. \|
88		\| [[https://ccleberg.github.io/orgo/guide/02-configuration.html][Configuration]] \| Every setting in =orgo.toml=, what it changes, and what it costs. \|
89		\| [[https://ccleberg.github.io/orgo/guide/03-collections.html][Collections]] \| Blog indexes, tag pages, pagination and RSS feeds. \|
90		\| [[https://ccleberg.github.io/orgo/guide/04-templates.html][Templates]] \| Layouts, and every variable a template can use. \|
91		\| [[https://ccleberg.github.io/orgo/guide/05-org-support.html][Org support]] \| Which org syntax is handled, which is not, and how the rest degrades. \|
92		\| [[https://ccleberg.github.io/orgo/guide/06-authoring.html][Authoring]] \| URLs, drafts, excerpts, tables of contents. \|
93		\| [[https://ccleberg.github.io/orgo/guide/07-incremental.html][Incremental builds]] \| How it decides what to rebuild. \|
94		\| [[https://ccleberg.github.io/orgo/guide/08-workflow.html][Watching and serving]] \| The write-save-see loop. \|
95		\| [[https://ccleberg.github.io/orgo/guide/09-auditing.html][Auditing]] \| Reading a corpus before trusting a tool with it. \|
96		\| [[https://ccleberg.github.io/orgo/guide/10-deploying.html][Deploying]] \| Producing a production build, and putting it somewhere. \|
97
98		** Building from a checkout
99
100		#+begin_src sh
101		cargo test # includes a differential check against Emacs, when present
102		cargo run -- serve docs -o docs/_site # read the documentation locally
103		#+end_src
104
105		** Licence
106
107		[[file:LICENSE][0BSD]]. Do what you like with it.

Commit 51d965d2ef

Commit `51d965d2ef`