Artifact [578078b75d]

Artifact 578078b75d1519975624f9df67e327f5699755ba88f453ffc02e436a59b52e1f:

• File Makefile — part of check-in [e2a2f28861] at 2026-04-26 07:52:11 on branch trunk — docs site + landing + Cloudflare auto-deploy (#6)

  * design: docs site + landing page + Cloudflare auto-deploy

  Mirror dagnats's docs/landing infrastructure for libfossil: a single-page landing at site/index.html (forked CSS/HTML, content rewritten), a Hugo + Hextra docs site at docs/site/, gomarkdoc-generated SDK reference under docs/site/content/docs/reference/sdk/, llms.txt artifacts, and a wrangler.jsonc that lets Cloudflare's git integration auto-deploy on push to main. Existing docs/*.md files move under docs/site/content/docs/.

  * design: correct landing-page path to Hugo layout override

  dagnats's working landing page lives at docs/site/layouts/index.html (a Hugo home-page layout override), not at site/index.html. The top-level site/index.html in dagnats is an older draft that the build pipeline ignores. Match the working setup.

  * design: align visual system + section list with live dagnats landing

  The earlier description came from dagnats's stale top-level site/index.html (JetBrains Mono + Instrument Serif italic + ember/teal accents, 8 sections). The live Hugo layout that actually serves at / uses Geist Mono only, prefers-color-scheme dual-mode (warm cream / warm dark), a single ember accent, and 7 sections (Install, What it is, Why you might want it, How it fits together, Compared to neighbors, What it is not, Get going). Update the spec to match what we are actually mirroring.

  * design: drop SDK regen from CF build to match dagnats exactly

  Earlier draft had CF install Go + gomarkdoc and re-run docs-gen-sdk on every deploy. dagnats does not do that; it relies on the pre-commit hook to keep committed SDK pages in sync, and ships only Hugo + llms-gen + hugo --minify in the CF build. Match that: smaller, faster CF build, no Go-runtime assumption about Workers Builds, and a true 1:1 mirror.

  * plan: docs site + landing + CF auto-deploy implementation steps

  11 tasks covering Hugo+Hextra bootstrap, content moves, gomarkdoc SDK generation with pre-commit drift check, llms.txt artifacts, Makefile targets, landing page fork from dagnats's live Hugo home layout, wrangler.jsonc for CF Workers Static Assets, README update, and PR creation.

  * docs(site): bootstrap Hugo + Hextra skeleton

  * docs(site): move existing docs into Hugo content tree

  * docs(site): fix links + H1s broken by docs-tree move

  - Drop .md extensions on Hugo cross-doc links - Switch source-code references to absolute github.com/danmestas/libfossil URLs (relative ../ paths broke when files moved 3 dirs deeper) - Align H1 of architecture.md and migration-from-fossil.md with their frontmatter titles

  * docs(site): add quickstart, examples, and SDK section stubs

  * docs(site): tighten quickstart snippets + reference index

  - Make the Sync example self-contained (open + sync, full main, real signatures) - Bridge from Clone to Open with a one-line prose link - Add a sentence to reference/_index.md so it does not render blank - Use the project's canonical "pure-Go, CGo-free" phrasing

  * docs(site): add docs-gen-sdk Makefile target + commit generated SDK pages

  * docs(site): pin gomarkdoc version + replace empty driver stubs with prose

  - Add GOMARKDOC_VERSION Makefile variable so contributors don't drift on output format when a new gomarkdoc ships - Drop the two driver packages (modernc, ncruces) from gomarkdoc and hand-write _index.md pages explaining the register-on-import contract; the stubs were byte-stable but rendered as visibly broken documentation

  * docs(site): add gen-llms-txt.sh + docs-gen-llms target

  * docs(site): switch llms-full frontmatter strip from sed to awk

  The sed range-negation pattern '/^---$/,/^---$/!p' silently re-opens a suppression range on any bare '---' in body content, eating Markdown horizontal rules and embedded YAML in fenced code blocks. The awk pattern strips the frontmatter only when it begins on line 1, leaving body content intact regardless of how many '---' lines it contains.

  * hooks: pre-commit fails when SDK pages drift from code

  * hooks: pre-commit re-installs gomarkdoc if it's the wrong version

  The drift check's existing gate just looks for gomarkdoc on PATH. A contributor with an older gomarkdoc installed locally would have the gate pass and then run regeneration with their stale binary, producing either a silent false-negative or a confusing OUT-OF-DATE error with no version hint. Compare the installed version against GOMARKDOC_VERSION from Makefile and re-install on mismatch. Best-effort; offline contributors can still commit.

  * docs(site): add docs-serve, docs-build, docs aggregate targets

  * docs(site): make docs aggregate parallel-safe via explicit deps

  The docs aggregate previously listed gen-sdk, gen-llms, and build as side-by-side prereqs. Make doesn't guarantee left-to-right ordering under -j, and gen-llms reads what gen-sdk writes, while build reads both. Encode the chain explicitly so 'make -j docs' is correct. Side benefit: 'make docs-build' standalone now produces a complete deployable site, matching contributor expectation.

  * site(landing): fork dagnats home layout; rebrand chrome

  * site(landing): rewrite §01–§07 content for libfossil

  * site(landing): use .ascii class for diagram + fix §03 phrasing

  * deploy: add wrangler.jsonc for CF Workers Static Assets

  * docs: point README at the new docs site (user: [email protected], size: 1607) [annotate] [blame] [check-ins using]

GOMARKDOC_VERSION := v1.1.0

.PHONY: test test-drivers test-otel test-all vet build setup-hooks docs-gen-sdk docs-gen-llms docs-serve docs-build docs

test:
	go test ./... -count=1 -timeout=120s

test-drivers:
	@echo "=== modernc (default) ==="
	go test ./... -count=1 -timeout=120s
	@echo "=== ncruces ==="
	go test -tags test_ncruces ./... -count=1 -timeout=120s
	@echo "=== all drivers passed ==="

test-otel:
	cd observer/otel && GOWORK=off go test ./... -count=1

test-all: test-drivers test-otel build
	@echo "=== all targets passed ==="

vet:
	go vet ./...

build:
	go build ./cmd/libfossil/

setup-hooks:
	git config core.hooksPath .githooks
	@echo "Pre-commit hook installed. Runs both drivers + DST + OTel (~45s) before each commit."
	@echo "Skip with: git commit --no-verify"

docs-gen-sdk:
	@command -v gomarkdoc >/dev/null 2>&1 || go install github.com/princjef/gomarkdoc/cmd/gomarkdoc@$(GOMARKDOC_VERSION)
	gomarkdoc --output docs/site/content/docs/reference/sdk/libfossil/api.md     ./
	gomarkdoc --output docs/site/content/docs/reference/sdk/cli/api.md           ./cli/
	gomarkdoc --output docs/site/content/docs/reference/sdk/db/api.md            ./db/
	gomarkdoc --output docs/site/content/docs/reference/sdk/observer/otel/api.md ./observer/otel/
	gomarkdoc --output docs/site/content/docs/reference/sdk/dst/api.md           ./dst/

docs-gen-llms: docs-gen-sdk
	bash scripts/gen-llms-txt.sh

docs-serve:
	cd docs/site && hugo server -D --port 1313

docs-build: docs-gen-sdk docs-gen-llms
	cd docs/site && hugo --minify

docs: docs-build
	@echo "=== docs: built into docs/site/public/ ==="