Obsidian To Hugo

Obsidian To Hugo is a lightweight, zero-dependency Python CLI that converts an Obsidian vault into Hugo content by transforming wiki links and highlights into Hugo shortcodes and HTML marks.

What is Obsidian To Hugo?

Obsidian To Hugo is an open-source command-line tool written in Python, installable via pip install obsidian-to-hugo. It takes exactly two arguments: the path to an Obsidian vault (--obsidian-vault-dir) and the path to a Hugo content directory (--hugo-content-dir). The tool clears the target content directory, copies all vault files, removes the .obsidian folder, and rewrites Obsidian's [[wikilink]] syntax into Hugo shortcode links such as [wikilink]({{< ref "wikilink" >}}). It also converts Obsidian's ==highlight== syntax into HTML <mark> tags. The package exposes both a command-line interface and a Python API with a run() method.

Key Features

• Wiki link conversion — Transforms Obsidian [[...]] links into Hugo {{< ref >}} shortcodes, including links with custom text, heading anchors, and _index pages.
• Highlight conversion — Replaces ==important== text with <mark>important</mark> HTML tags.
• Clean destination — Deletes and recreates the Hugo content directory before copying, so outdated files are removed automatically.
• Private settings removal — The .obsidian folder is stripped immediately after copying, keeping local configuration out of the published site.
• Custom filters — Accepts a list of functions via the filters argument; each function receives the file path and contents and returns True to copy the file or False to skip it.
• Custom processors — Accepts a list of functions via the processors argument; each function takes file contents as a string and returns a processed string, applied after the default transformations.
• Zero dependencies — Uses only the Python standard library, so installation stays small and portable.

Who is it for?

• Obsidian users publishing with Hugo: They can write notes in Obsidian and run one command to produce a Hugo-ready content folder without manually editing every internal link.
• Static site developers: They get a predictable content directory with Hugo {{< ref >}} shortcodes that resolve cross references at build time.
• Writers automating their pipeline: They can use filters to exclude drafts and processors to add front matter or apply other content modifications before publishing.

What can you do with Obsidian To Hugo?

• Bloggers: Convert a vault full of notes into Hugo markdown with working internal links, then run hugo to build the site.
• Knowledge base managers: Use filter functions to keep private or in-progress notes out of the public content directory.
• Tooling developers: Write custom processors to insert metadata, convert syntax, or restructure each file's contents as part of the conversion.

How does it work?

Run python -m obsidian_to_hugo --obsidian-vault-dir=<path> --hugo-content-dir=<path> from the terminal. The tool then clears the content directory, copies all vault files, removes .obsidian, and applies the link and highlight replacements. The Python API works the same way: instantiate ObsidianToHugo with the two directory paths and call run().

Pros and cons

• Pros: Simple two-argument CLI; zero external dependencies; extensible through filters and processors; handles common Obsidian syntax automatically.
• Cons: There is currently no way to escape wiki links, so every matching [[...]] is converted — workarounds like inserting an invisible space are not recommended by the author.

FAQ

Does Obsidian To Hugo support custom transformations beyond wiki links?

Yes. You can pass a list of processor functions to the ObsidianToHugo constructor. Each processor receives the file contents as a string and returns the processed string; custom processors run after the default conversions.

How can I exclude certain files from publishing?

Add a filter function to the filters argument. The function is called for each file with its path and contents; returning False causes the file to be skipped and not copied into the Hugo content directory.

What happens to the .obsidian folder during conversion?

The .obsidian directory is removed immediately after copying the vault contents, so your local Obsidian settings are never published with the site.

How do I install Obsidian To Hugo?

Install it from PyPI with pip install obsidian-to-hugo, then run it either as a module with python -m obsidian_to_hugo or through the Python API.

Does this tool work with any Hugo theme?

The tool only transforms the content directory; it doesn't affect Hugo theme compatibility. Because it converts links to standard Hugo {{< ref >}} shortcodes, any theme that uses Hugo's built-in shortcode handling will work.