Devlogs
The build diary
What changed this week, what broke, and what I got wrong. These are not tutorials and they do not pretend the work went smoothly.
Two UI critique rounds
A UX review and a scored critique (27 out of 40) on GitBasedDocs, what each one found, and the fixes that landed as one commit per finding.
Heavy Markdown, light pages
Shiki renders code on the server, Mermaid loads only on pages with a diagram, rendered HTML is cached per blob sha, and one misplaced import that shipped the whole pipeline to the browser is gone.
The $5 problem
remark-math read "costs $5 a month, or $50" as a formula. A small remark plugin applies the Pandoc and Obsidian dollar rule so prices stay text and real math still renders.
Making an Obsidian vault render on the web
GitBasedDocs now renders Obsidian callouts, wikilinks, highlights and safe inline HTML, strips %% comments before they reach the database, and keeps folder names and .trash the way Obsidian does.
Building GitBasedDocs with Claude Code
GitBasedDocs was built with Claude Code over two days and 55 commits. The rules file, one commit per task, a Markdown task board as shared state, and the places where I had to step in.
Who changed this page?
GitBasedDocs pages now show who changed them last, pulled from the GitHub commit list at sync time. The commit id and GitHub link shipped for editors too, then moved to admins only.
Tests without a test runner
GitBasedDocs has 11 runnable check files and no test framework. How they work, the guard that keeps them off the real database, and why lint, typecheck and build close the gate.
One process, one SQLite file
The GitBasedDocs deploy is one Node process and one SQLite file on a volume. Why it has to be a single instance, how migrations run on the first database call, and why the build never opens the database.
404, never 403: access control that doesn't leak project names
How GitBasedDocs keeps each client inside their own projects: one access gate, the same 404 for every refusal, images behind the same check, and JWT sessions that still notice a deactivated user.
Specs before code: the plan behind a two-day build
The first GitBasedDocs commit was almost all plan: research notes, feature specs and task cards. How that plan was shaped, and the four places reality corrected it.
Why I put a login in front of a GitHub repo
GitHub can't give a reader one folder of a repo, so sharing client docs from a single Obsidian vault needed an app in front of it. This is the problem GitBasedDocs solves and the shape it took.
Green webhook deliveries, and nothing synced
The GitBasedDocs webhook passed every test, then real pushes stopped updating the app while GitHub showed green deliveries. The causes were the hook URL and GitHub's default form content type.
Syncing from GitHub without Actions
How GitBasedDocs keeps pages fresh from a private repo with nothing installed in it: one ref call to check for changes, one tree call on a change, and blob fetches only for files whose sha moved.