From Obsidian Notes to a Static Hugo Blog

Why I write in plain-text Markdown, why I compile with Hugo, and how a declarative Python CLI manages the publishing pipeline.

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:

1
2
3
4
5
Σ/Blog/
├── Blog Index.md
├── drafts/
├── images/
└── posts/

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:

1
2
hugo new site CS-Topics
cd CS-Topics

However, a raw rsync between an Obsidian vault and a Hugo project is not enough:

  1. Obsidian embeds attachments using double-bracket wiki-links (![[...]]), which standard CommonMark parsers do not resolve into ![Alt](/images/...).
  2. 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.
  3. 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):

1
2
3
site   = "/Volumes/LCS.Data/Blog/CS-Topics"
posts  = "/Users/lcs-dev/Desktop/LCS-Vault/Σ/Blog/posts"
images = "/Users/lcs-dev/Desktop/LCS-Vault/Σ/Blog/images"

The tool exposes four idempotent commands:

1
2
3
4
blog status          # Inspect configuration, git state, and pending file diffs
blog sync --dry-run  # Preview the exact execution plan without touching disk
blog sync            # Atomically mirror posts and referenced images into the site
blog publish         # Sync, run an isolated Hugo check-build, commit, and push

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 in images/. If even one referenced image is missing, the entire sync is refused before a single byte is written.
1
2
3
4
5
6
EMBED = re.compile(
    r"(?P<bang>!?)\[\[(?P<name>[^\[\]|#\n]+?"
    r"\.(?:png|jpe?g|gif|bmp|webp|svg|avif))"
    r"(?:\|(?P<label>[^\[\]\n]*))?\]\]",
    re.IGNORECASE,
)

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():

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
def _write(target: Path, data: bytes) -> None:
    """Replace a file atomically through a temporary file beside it."""
    target.parent.mkdir(parents=True, exist_ok=True)
    descriptor, name = tempfile.mkstemp(
        prefix=f".{target.name}.", suffix=".tmp", dir=target.parent
    )
    try:
        with os.fdopen(descriptor, "wb") as handle:
            handle.write(data)
        os.chmod(name, 0o666 & ~_umask())
        os.replace(name, target)
    except BaseException:
        Path(name).unlink(missing_ok=True)
        raise

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.