Skip to content

feat(site): onboard docs-engine, publishing doc/ as the guide - #6

Merged
burinc merged 1 commit into
mainfrom
feat/docs-engine-site
Sep 6, 2026
Merged

burinc merged 1 commit into
mainfrom
feat/docs-engine-site

Conversation

@burinc

@burinc burinc commented Sep 6, 2026

Copy link
Copy Markdown
Contributor

ebb had no docs/ directory at all — unlike raylib-android (which had full
scaffolding, just disabled while the repo was private), this is a
from-scratch onboarding.

doc/evaluation.md, doc/conformance.md and doc/adr/001-fiber-affinity.md
are real, reader-oriented documentation — but they're also load-bearing:
test/ebb/conformance_test.clj hardcodes "doc/divergences.edn" and
"doc/conformance.md" as its gate, and nine files under src/ebb/impl/
carry See doc/conformance.md comments. Moving them would mean rewriting
that gate and a dozen-plus source comments, so instead
docs/guide/{evaluation,conformance}.md and
docs/guide/adr/001-fiber-affinity.md are relative symlinks into doc/
— same pattern as awesome-jolt's guide/index.md → README.md. doc/
stays the one canonical path every test and source comment already points
at; the site gets a window into it, not a copy.

docs/guide/index.md is a new page (not a symlink) — ebb's README is
already a GitHub-facing pitch, so the guide gets its own overview that
indexes the three real pages, matching glitter's README-vs-guide split.

Known gap, not fixed here

conformance.md's own prose links to divergences.edn (the machine-readable
half of the same registry). That's an .edn file, not a doc page the engine
renders, and publishing it as a site asset would mean rewriting that link in
the canonical file the test suite reads verbatim — not worth doing just to
suit the site's layout. That one link 404s on the published site
specifically; it's fine on GitHub, and the guide page's own prose says so
and points there instead.

Verified locally

Against docs-engine v0.2.0:

  • bb build succeeds, docs/check-site.sh passes (index, guide overview,
    evaluation, conformance and the ADR all present).
  • Served the build under /ebb/ (not root) — all 10 emitted URLs return
    200, nothing escapes the base path, no unrendered {{site-base}}.
  • Confirmed the cross-links inherited from evaluation.md/conformance.md/
    the ADR (written assuming doc/'s own flat-plus-adr/ layout) correctly
    rewrite to .html at the same nesting depth under docs/guide/.
  • Confirmed the divergences.edn gap is exactly that gap and nothing else
    (a clean 404, not a broader breakage).

Not done here

GitHub Pages has no site at all for this repo yet. Enabling it is its own
explicit step, done right before merge per the org's own migration runbook,
not bundled into this PR.

ebb had no docs/ directory at all - unlike raylib-android (which had
full scaffolding, just disabled while the repo was private), this is
a from-scratch onboarding.

doc/evaluation.md, doc/conformance.md and doc/adr/001-fiber-affinity.md
are real, reader-oriented documentation, not internal notes - but they
are also load-bearing: test/ebb/conformance_test.clj hardcodes
"doc/divergences.edn" and "doc/conformance.md" as its gate, and nine
files under src/ebb/impl/ carry "See doc/conformance.md" comments.
Moving them would mean rewriting that gate and a dozen-plus source
comments. Instead docs/guide/{evaluation,conformance}.md and
docs/guide/adr/001-fiber-affinity.md are relative symlinks into doc/,
same pattern as awesome-jolt's guide/index.md -> README.md: doc/ stays
the one canonical path every test and source comment already points
at, and the site gets a window into it rather than a copy.

docs/guide/index.md is a new page, not a symlink - ebb's README is
already a GitHub-facing pitch (install, quick example, a four-line
differences summary), so the guide gets its own "why this exists"
overview that indexes the three real pages, matching glitter's own
README-vs-guide/index.md split.

Known gap, not fixed here: conformance.md's own prose links to
divergences.edn (the machine-readable half of the same registry).
That's an .edn file, not a doc page the engine renders, and publishing
it as a site asset would mean rewriting that link in the canonical
file the test suite reads verbatim - not worth doing to suit the
site's layout. That one link 404s on the published site specifically;
it's fine on GitHub, and the guide page's own prose says so and points
there instead.

.github/workflows/site.yml + docs/check-site.sh: build and publish via
the org's shared jlt-commons/ci-builds reusable workflow. The checks
include a byte-size floor on the two symlinked pages specifically,
since a stale/broken symlink would still let the build succeed - slurp
on a dangling link fails loud, but a symlink repointed at the wrong
file would not.

Verified locally against docs-engine v0.2.0: `bb build` succeeds,
docs/check-site.sh passes (index, guide overview, evaluation,
conformance and the ADR all present), and serving the build under
/ebb/ (not root) returns 200 for all 10 emitted URLs with nothing
escaping the base path. Confirmed the inherited cross-links between
evaluation.md/conformance.md/the ADR (written assuming doc/'s own
flat-plus-adr/ layout) correctly rewrite to .html at the same nesting
depth under docs/guide/, and confirmed the divergences.edn gap is
exactly that gap and nothing else (404, not a broader breakage).
@burinc
burinc merged commit 5410191 into main Sep 6, 2026
4 checks passed
@burinc
burinc deleted the feat/docs-engine-site branch September 6, 2026 13:16
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant