freshdocs 0.3.1

Follow-up to 0.3.0, closing the two caveats that release shipped with.

Documentation repositories are pinned to a commit

A separate documentation website repository carries no version tags, so 0.3.0 read it from a moving branch and labelled the result live-unversioned. That branch keeps moving, so the cited URL stopped matching what was indexed.

The branch is now resolved to a commit before fetching. The source URL is immutable, and the snippet is labelled docs-commit <sha>:

[1] hono 4.13.5 fetched 2026-09-04 docs-commit c48b858 - Bearer Auth Middleware
source: https://raw.githubusercontent.com/honojs/website/c48b858a67.../docs/middleware/builtin/bearer-auth.md

docs-commit is deliberately distinct from exact-ref: it is current documentation prose read at a fixed point, not the library's own version tag. A branch that cannot be resolved is reported as a warning.

Stale-format cache entries can be dropped

0.3.0 marked cached versions built by an older indexer as stale but offered no way to clear them, and re-indexing every historical version took hours while storing documentation nobody had asked for.

freshdocs prune            # --dry-run to preview, --include-current to go further

Pruning is instant and safe: the staleness check re-fetches a version with the current pipeline the moment a project pins to it. On a 35-library cache this dropped 149 versions and 4011 chunks in under a second, and doctor reports all cached versions at format 2.

Use freshdocs sync --outdated instead when you want those versions re-indexed up front.

Install

uv tool install git+https://github.com/Supersynergy/freshdocs@v0.3.1