Pull request #87 · stacks/bunpress

Summary

Source-relative Markdown links now resolve from the authored file to the generated documentation route in native builds and dev serving. A finite source/locale catalog handles nested pages, index/README routes, encoded destinations and explicit language selection while preserving source files, external/evidence URLs, images and literal code.

selected source + locale
  -> shared Markdown rendering and source-link resolution
  -> complete staged build publication / dev response

Builds use unique staging directories, serialize a shared output in one process, lock it against other processes and restore previous output if publication fails. Missing linked sources and canonical route collisions refuse publication.

Includes retain per-file origins for inline links. Reference definitions combined with includes remain explicitly unsupported because the native parser does not expose definition origins. Native parser probes distinguish actual reference bindings from literal code, with a documented 256-candidate limit. Standalone reference links remain supported.

Refs #86 and stacksjs/drone#39. Follow-up #88 tracks full reference-definition provenance across includes. Package release and Drone/Buddy adoption remain separate pending work.

Evidence

Before: Public native regressions reproduced literal .md routes, concurrent builds reporting success with missing pages, encoded asset rendering failure, wrong explicit-language selection and wrong included-file destinations. Original failures were retained. After: Native build/dev regressions cover these behaviors, failed reads, retained locks, stale output removal, rollback, recursive origins, literal code and explicit refusal of ambiguous reference bindings.
bun test: 595 passed, zero failures, 1,731 assertions across 47 files.
Native library/plugin build, root/package type checks and Pickier lint passed. Two unchanged lint warnings remain.
Native own-docs build produced 36 pages. Built CLI was exercised from a fresh fixture project; an independent HTML parser verified rendered targets and anchors, code groups, locale choice and opaque asset URLs. Unsupported reference/include builds exited 1, dev returned 500, and previous output remained byte-identical.

Merge Danger

Door: Two-way. Revert the source change to restore previous rendering. No dependency lock changes or automatic rewriting of input Markdown.

Blast Radius: Documentation. Existing authored .md links become generated routes. Output collisions and unsupported include/reference combinations now fail explicitly; documentation describes these limits and stale-lock recovery.