Releases

A release that mostly makes the docs site itself nicer to build and read.

Bases grow a reading view. A cards view whose order includes a note.body (or file.body) column now renders each note's full body inside the card, laid out as a single readable column with the other columns as a meta row above — a changelog or release-notes view, not a tile grid. This very Releases page is one. A base can also set a top-level title: to name its page, and any page can now carry sidebar: false in its frontmatter to stay out of the nav tree while still being reachable — which is how these release notes surface here without cluttering the sidebar.

The /diff timeline is now optional. [[configuration#features|[features]]] gains a diff toggle (on by default). Turn it off and the /diff workspace and its client assets are dropped from the build entirely — a leaner site when you don't want a git-history view.

A logo, and a docs.rs fix. docgen gets a hub-and-orbit logo and favicon. And docgen-rs grew a real library target so docs.rs stops failing to build the crate.

The S3 TLS work started in 0.7.0, finished properly.

Two things landed. The provider guard now actually discriminates — the earlier version could accept the wrong crypto provider instead of enforcing the one intended, so this tightens it to install exactly the provider it means to. And TLS is enabled again and, more importantly, proven: a MinIO end-to-end test drives a real upload over https://, so the path that broke silently before now fails loudly the moment it regresses.

The lesson, kept for next time: a config knob that touches transport security is not fixed until an end-to-end test exercises the encrypted path.

docgen lint — a subcommand that checks a site for publishing problems before it ships: broken links, missing assets, malformed diagrams and frontmatter, structural oddities. It lives in its own leaf crate, docgen-lint, taking the workspace to fourteen crates.

Lint reuses the same resolution the build uses, so what it flags is exactly what the build would produce — no second, drifting notion of "valid". A site-lint fixture and integration tests pin the behaviour down, checking both that real problems are caught and that clean sites pass clean.

As with bases, an adversarial review followed implementation and its findings were resolved before merge.

A single fix, but a load-bearing one: S3 offload over TLS.

The attohttpc client pulls in rustls, and rustls insists on exactly one active crypto provider. Two were being linked in, so provider selection was ambiguous and HTTPS requests to the bucket could not complete. This release pins rustls to one provider, restoring https:// endpoints.

The story does not quite end here — a follow-up in 0.8.1 proves the TLS path end-to-end against a live MinIO server and hardens the provider guard that this release put in place.

Obsidian Bases support — the .base format, implemented as a pure leaf crate: value model, lexer, Pratt parser, tree-walking evaluator, the function and method library, and static table/cards/list rendering.

A .base file becomes its own page and a ```base block renders inline, both computed at build time. The evaluator is deliberately Obsidian-tolerant: unknown symbols and functions evaluate to empty rather than failing, matching how Obsidian itself behaves, so a base written in the app renders here without adjustment.

Being a parser fed by author input, it is also budgeted — parser depth and node limits, and an evaluator depth guard — so an adversarial expression errors out instead of overflowing the stack.

An adversarial review after implementation found thirteen real bugs, all fixed before merge. The page you are reading is itself a base.

Build-time PlantUML rendering — plus the docgen-bases crate reserved on crates.io ahead of 0.6.0, taking the workspace to thirteen crates.

PlantUML has no browser renderer, so unlike mermaid it cannot be deferred to the reader. docgen renders each diagram against a PlantUML server while building and inlines the resulting SVG, leaving the published site fully static with no runtime dependency on that server.

Two decisions make it practical. Every diagram is cached on disk, keyed by a hash of its source and the server URL — so incremental dev rebuilds stay fast, and a full rebuild still succeeds for cached diagrams even when the server is unreachable. And a diagram never breaks the build: an unreachable server, a syntax error, or a missing src file each render a detailed, visible error block naming the actual failure, and the build goes on.

The responsive mobile layout: drawers instead of fixed rails, an overflow menu for the topbar, and tables that scroll inside their own box rather than dragging the page sideways.

That last idea — content that does not fit should scroll within its container, never widen the page — is a rule the project keeps rediscovering, most recently for wide PlantUML diagrams.

Follow-up fixes landed in the same cycle for the mobile right-rail height, the drawer/topbar overlap, and overflow-menu items that stretched instead of keeping their intrinsic width.

This release also stood up this documentation site, built by docgen from workspace source and deployed to GitHub Pages on every push to master.

S3-compatible asset offload, and the first new crate since the initial release: docgen-s3 (eleven crates now publish in lockstep).

Large attachments do not belong in a git repo or a Pages artifact. With an [s3] section configured and credentials present, a production build uploads them to a bucket and rewrites their URLs. The uploader is content-hashed and idempotent: it lists the bucket once, then puts only what is missing, so rebuilding an unchanged site uploads nothing. A build-time AssetUrlResolver hook in docgen-core keeps the rewrite pass unaware of S3 entirely — the leaf crate owns all the I/O.

Two guards shipped with it. Dev mode never offloads, so local iteration cannot write to a real bucket. And the list prefix is trimmed of stray slashes: without that, a configured prefix = "/assets" listed under /assets while keys lived under assets/, so the diff found nothing present and re-uploaded everything, every build.

The feature is opt-in (cargo install docgen-rs --features s3) and off by default.

Two navigation fixes, both of the sort you only notice when they are wrong.

The sidebar lost its scroll position on every page navigation, so readers deep in a long tree were thrown back to the top each time they followed a link. It now persists.

The second continues the base-path thread from 0.2.0: relative asset and page URLs now resolve to base-absolute clean URLs. Relative links appear to work right up until a page moves depth, or the site moves under a sub-path — the exact case 0.2.0 introduced.

An incremental rebuild engine for the dev server — the release that made docgen dev feel immediate on a large site, by rebuilding what a change actually touched instead of the whole site on every keystroke.

Cross-document features make this genuinely hard: a change is only safely local if nothing else depends on it. That constraint is why the engine has to reason about staleness rather than just diff file contents, and it is why a later feature like Bases has to force a full rebuild whenever a .base consumes the corpus.

Windows left the release matrix in this cycle: the katex crate's default quick-js backend does not compile on the MSVC target.

Sub-path deploys, which is what you need for a project page served from example.github.io/my-project/ rather than a domain root.

Getting a site to work under a base path is the kind of change that is only finished when every URL respects it. The graph's links were the ones still pointing at the root. Alongside that, GitLab Pages is now auto-detected, so its base path is inferred rather than configured by hand.

Dependabot started watching the dependency tree here.

A same-day follow-up to 0.1.0, mostly correctness.

The doc graph rendered twice, which showed up as a duplicate on zoom. The dev server failed on non-ASCII request paths — they are now decoded, with the base prefix stripped properly.

The most consequential fix was the smallest: dropping git2's default features removed the openssl-sys dependency, and with it a system build requirement that had no business in a tool whose entire premise is cargo install and nothing else. The same instinct — keep the dependency graph free of C toolchain prerequisites — comes back later, in 0.4.0.

This release also opened the project up: an MIT licence and a real README.

The first public release — ten crates published to crates.io at once.

The headline was the CodeMirror 6 split editor at /edit/<slug>, replacing an earlier CM5 overlay. Its live preview renders through the real page pipeline rather than a lookalike, so what you see while typing is what the build produces.

Also in the initial cut: the :include directive for transcluding _partials (excluded from published pages), the interactive doc graph, a sidebar that persists folder collapse state to localStorage, an eight-theme switcher with a settings menu, and a home dashboard. Discovery learned to prune hidden and vendor directories (node_modules, target, .git, .obsidian) so a stray build folder could not become documentation.