krz/orgo

  1# Changelog
  2
  3What changed and why, newest first. Entries name the *behaviour* that moved, since that is
  4what a rebuild will show you.
  5
  6Two conventions worth knowing before reading:
  7
  8- **A cache-format bump is not a change you need to act on.** The incremental cache is
  9  versioned and discards itself; a bump means the next build re-renders everything once.
 10- **Output changes are called out.** orgo aims at what Emacs exports from the same
 11  file, so an entry that says "now renders X" means your pages will change. That is the
 12  product, not a regression — but it belongs in a changelog rather than a diff you find
 13  later.
 14
 15Versions follow the compatibility promise in the README: config keys, template variables,
 16CLI flags and URLs are the stable surface.
 17
 18## 0.19.1
 19
 20- Footnote back-links carry `aria-label="Back to reference N"`, and the notes section is
 21  labelled. A link whose only visible content is `↩` has that glyph as its whole
 22  accessible name, so a screen reader announced "left arrow with hook" once per note with
 23  no way to tell them apart.
 24
 25## 0.19.0
 26
 27- **Full-content collections.** `include_content = true` gives a listing template each
 28  entry's rendered HTML as `entry.content` — a feed that carries whole posts rather than
 29  excerpts. Rendered only when the listing is actually rebuilt, so a cached feed costs
 30  nothing.
 31- **Fixed: a listing could show a stale excerpt.** Its cache key covered a hand-picked set
 32  of fields, and the excerpt was not among them, so rewriting a post's first paragraph
 33  left the old text on the index until something unrelated invalidated it. Entries are now
 34  hashed through their serialization, which cannot drift from what a template can read.
 35  Editing a post's body now rebuilds the listings that show it.
 36- `page.toc` entries carry `number`, so a site with section numbering on can number its
 37  contents list to match its headings.
 38
 39## 0.18.0
 40
 41Release engineering, so that a version number is worth reading.
 42
 43- **A written compatibility promise.** Config keys, template variables, CLI flags and URLs
 44  are the stable surface; the incremental cache, HTML details and the Rust API are not.
 45  In the README, and in the guide under *Versioning and upgrades*.
 46- **CI** on Linux and macOS: build, test, clippy as an error, and the documentation site
 47  built with `--strict`. Emacs is installed on both, so the oracle suite runs for real
 48  instead of skipping.
 49- **A checked MSRV**, 1.88 — which is how it came to be 1.88 rather than the 1.82
 50  orgo's own code needs. The floor comes from dependencies, and nobody finds that out
 51  by reasoning about it.
 52- **Release binaries** for macOS (arm64, x86_64) and Linux (gnu, musl), built on tag into
 53  a draft release. The tag is checked against `Cargo.toml` before anything is built.
 54- A `LICENSE` file to go with the MIT declaration, crates.io metadata, and a release
 55  profile that produces a 5.0 MB binary rather than 6.5 MB.
 56- This changelog, and `RELEASING.md`.
 57
 58## 0.17.0
 59
 60- **Asset directories outside the source.** `[build] assets = ["../theme/static"]` copies
 61  a directory's contents to the site root. A site's static files do not always live where
 62  its writing does, and copying them next to the writing is how a repository ends up with
 63  two of every stylesheet. `watch` and `serve` watch these directories too. Two files
 64  claiming one URL is a build error naming both.
 65- **Template hashing is per template.** A page's render key covered every template, so
 66  editing a feed template re-rendered the whole site. It now covers the layout the page
 67  uses plus what that layout extends, includes or imports. On a 196-page site, editing the
 68  feed template renders one page instead of 196.
 69- Cache format 7.
 70
 71## 0.16.0
 72
 73- **Org's entity table.** `\alpha`, `\rarr`, `20\deg` and the other 412 names, generated
 74  from Emacs' own `org-entities`. An unknown name stays literal; `#+OPTIONS: e:nil` turns
 75  the table off. *Output changes* for any page using entities.
 76- **Table captions.** `#+CAPTION:` above a table becomes a numbered `<caption>`.
 77- **`#+INCLUDE:` reports itself.** It was inert and silent, which publishes a page with
 78  content missing and nobody told. Now a diagnostic, and `--strict` makes it a failure.
 79- The Emacs oracle separates deliberate divergence from defects. Every difference from
 80  org's exporter is named and justified, and a test asserts there are no others.
 81
 82## 0.15.0
 83
 84Export parity, from a page-by-page diff of a 179-file corpus against the site Emacs
 85publishes from the same sources. **All of these change output.**
 86
 87- Heading levels are relative to a document's shallowest heading, as org exports them.
 88- Org's text conversions: `--`, `---`, `...`, and `x^2` / `a_{b}`. Never inside verbatim,
 89  code, source blocks or LaTeX. `#+OPTIONS: -:nil`, `^:nil` and `^:{}` all work.
 90- Captioned figures are numbered `Figure N:`.
 91- A caption attaches to the element *directly* below it; a blank line between attaches to
 92  nothing.
 93- Checkboxes render as org writes them, which keeps the `[-]` partly-done state a disabled
 94  `<input>` could not express. `[@4]` sets a list item's number.
 95- A table's special marker column and its marker rows stay out of the output.
 96- `#+BEGIN_NOTE` and any other unrecognised name is a special block: a div holding parsed
 97  org rather than a `<pre>` of literal text. Verse keeps its line breaks.
 98- Emphasis borders forbid whitespace and nothing else, so `="proxied":false=` is verbatim
 99  and `~~/.config/doom/config.el~` is a path that starts with a tilde.
100- Listings sort on the time of day when a timestamp carries one.
101- Cache format 6.
102
103## 0.14.0
104
105- **Per-page layouts.** `[[pages]]` rules map a source path to a template, and
106  `#+TEMPLATE:` on a page overrides any rule. A missing template fails the build naming
107  the page, the template, and what does exist.
108- `page.year`, for grouping a listing by year with minijinja's `groupby`.
109- An explicit nav can order generated pages among authored ones. `nav.mode = "none"` now
110  really means none.
111
112## 0.13.0
113
114- Bundled TOML and Org syntax definitions, a `syntaxes_dir` for your own, and org's comma
115  escape (`,* heading` inside a block).
116
117## 0.12.0
118
119- `serve`: a development server with live reload, bound to loopback.
120- A documentation site under `docs/`, built by orgo itself.
121
122## 0.11.0
123
124- Table of contents as `page.toc`, section numbers, and org's `#+OPTIONS:` per-file
125  switches.
126
127## 0.10.0
128
129- Excerpts, word count, reading time, a `truncate` filter, and `#+DRAFT:` pages.
130
131## 0.9.0
132
133- `watch`: rebuilds on OS filesystem events, debounced.
134
135## 0.8.0
136
137- `site.base_url`, the `absolute` and `rfc822` filters, canonical links, and an RSS feed
138  in the scaffold that validates.
139
140## 0.7.0
141
142- Pagination for large listings, with a `paginator` template context that composes with
143  grouping.
144
145## 0.6.0
146
147- Grouped collections: one page per tag plus a tag index.
148- Generated listing pages (`[[collections]]`), sorted indexes, and feeds via XML
149  templates.
150- A config file, user templates, nav modes, an `init` scaffold, and discovery that will
151  not publish `.git`.
152
153## 0.5.0
154
155- Parse diagnostics carry `file:line`, and pages render in parallel.
156- The corpus audit (`orgo audit`) and the `emacs --batch` oracle.
157- `#+SLUG:` decides a page's output filename — found by auditing a real corpus, where it
158  affected 169 of 182 URLs.
159
160## 0.4.0
161
162- The full v1 construct scope, with the IN/OUT line under test.
163
164## 0.3.0
165
166- The incremental build layer: content, config and template hashing, a dependency graph,
167  per-page render keys, and a persisted cache manifest. A full build and an incremental
168  build produce byte-identical output.
169
170## 0.2.0
171
172- Multi-file site builds: a symbol table, internal link resolution, minijinja templates,
173  tables and footnotes.
174
175## 0.1.0
176
177- Parse and render a single `.org` file to HTML.