Writing is the sharpest test of understanding. A concept in operating systems, probability theory, or algorithm design often feels clear in your head until you try to state its invariants in prose or implement it without hand-waving. This blog is where I turn study notes and mathematical derivations into self-contained technical articles.
To keep the focus entirely on content, the publishing pipeline must have zero friction. Every article starts as a local Markdown file inside an Obsidian vault, gets validated and transformed by a custom Python CLI packaged with Nix, and compiles into a static site via Hugo.
Local-First Authoring in Obsidian
A technical knowledge base should outlive any proprietary platform. I store my notes in Obsidian because it operates directly over a local directory of plain-text UTF-8 Markdown files, with native support for $\LaTeX$ math blocks and fenced code snippets.
Inside the vault, the blog lives in a dedicated subtree:
| |
Notes remain in drafts/ while proofs or benchmarks are still taking shape. Once an article is ready for publication, moving it into posts/ exposes it to the synchronization tool.
Static Compilation with Hugo
Dynamic CMS backends introduce databases, runtime attack surfaces, and query latency for pages whose content only changes on git push. Hugo compiles Markdown and KaTeX math into static HTML at native Go speed—building over a hundred pages in under 300 milliseconds.
Initializing the site and theme requires only Git, Go, and Hugo:
| |
However, a raw rsync between an Obsidian vault and a Hugo project is not enough:
- Obsidian embeds attachments using double-bracket wiki-links (
![[...]]), which standard CommonMark parsers do not resolve into. - Only images actively referenced by published articles should be copied to Hugo’s
static/images/directory, without disturbing site-wide assets like logos or favicons. - Interrupted writes, broken image references, or unmounted drives must never corrupt the published repository.
The blog CLI: Atomic Sync and Verification
Rather than gluing together fragile shell scripts, I wrote a dependency-free Python 3.12 CLI (blog), packaged declaratively via Nix and configured through Home Manager (~/.config/blog/config.toml):
| |
The tool exposes four idempotent commands:
| |
1. Pure Planning Phase (content.plan)
Before modifying any file, blog builds an in-memory Plan comparing the vault against the Hugo tree:
- Empty-Vault Guard: If the vault’s
posts/directory contains zero Markdown files—typically indicating an unmounted volume—the sync aborts immediately rather than wiping the site. - Symlink Refusal: All vault reads open descriptors with
os.O_RDONLY | os.O_NOFOLLOW. Symlinks and special files are skipped and reported so nothing outside the vault boundary can ever be pulled into the repository. - Attachment Verification: Every Obsidian image embed is rewritten into a URL-encoded
/images/...Markdown link, and the planner verifies that the target binary exists as a regular file inimages/. If even one referenced image is missing, the entire sync is refused before a single byte is written.
| |
2. Lock-Protected Atomic Writes (content.apply)
When the plan is clean, blog acquires an exclusive non-blocking kernel lock (fcntl.flock) on $XDG_STATE_HOME/blog/lock, copies any file about to be overwritten or deleted into a timestamped backup directory, and writes updates through adjacent temporary files (tempfile.mkstemp) followed by an atomic POSIX os.replace():
| |
3. Isolated Build Check and Scoped Git Push (repository)
During blog publish, the CLI runs hugo --minify into a disposable tempfile.TemporaryDirectory with HUGO_BUILD_NOJSCONFIGINASSETS=true so the working tree remains pristine. Only if Hugo exits with status 0 does blog stage content/posts and static/images—leaving any unrelated edits in the repository untouched—and push the commit to origin/main.