How this works

Tue, 01 Sep 2026 22:33:16 +0000

How this works#

Three directories, one direction of travel:

The vault#

vault/ is the Obsidian vault and the only place you type. It knows nothing about Hugo beyond one front matter key, publish.

The sync script#

bin/vault-sync.py is where the actual translation happens, because Hugo does not understand Obsidian’s markdown. Hugo’s maintainers closed the wikilink feature request as not planned, so [[Note]] reaches Goldmark as literal text and renders as literal text. The script rewrites it into a relref shortcode, which Hugo resolves at build time and fails loudly on if the target disappears.

Syntax cheatsheet

Tue, 01 Sep 2026 22:33:16 +0000

Syntax cheatsheet#

What the sync script does with Obsidian-flavoured markdown.

Links#

In the vault	On the site
`[[How this works]]`	link to that page
`[[How this works\|custom text]]`	link with your label
`[[How this works#The vault]]`	link to that heading
`[[#Links]]`	link inside the same page
`[[Half-baked idea]]` (unpublished)	plain text, plus a warning
`[[Nonexistent]]`	plain text, plus a warning

Links to unpublished notes degrade to plain text rather than breaking the build. Run make check to turn those warnings into a failure instead.