Front matter is the backbone of content organization in static site generators like Hugo. If you’re migrating from Obsidian—a popular note-taking tool that also uses front matter—you might encounter challenges aligning your existing metadata with Hugo’s expected format. This post explores these challenges, the key differences between Obsidian’s and Hugo’s front matter structures, and strategies for mapping custom fields effectively.

Understanding the Differences

Obsidian’s Front Matter Approach

Obsidian employs YAML front matter primarily for metadata management within Markdown files. The structure is freeform, meaning you can define almost any variable that suits your needs. This flexibility makes Obsidian an excellent choice for personal knowledge management, but it also introduces inconsistencies when migrating to a structured system like Hugo.

A typical Obsidian front matter section might look like this (in some cases, users like to use emojis in tags to visually indicate the status of a note, such as draft, perfectly written, or needing more links):

---
title: "Migrating from Obsidian to Hugo"
date: 2024-03-09
tags: 
  - "obsidian"
  - "hugo", 
  - "📓"
category: "Tech"
custom_field: "Some custom metadata"
---

Here, the custom_field is user-defined and doesn’t adhere to any predefined schema. This level of flexibility is great for note-taking but can lead to inconsistencies when integrating with Hugo’s templating engine.

Hugo’s Front Matter Standards

Hugo, being a static site generator, requires more structure. It has a set of predefined front matter variables that directly impact how content is processed, displayed, and categorized. Unlike Obsidian, Hugo strictly interprets certain fields for sorting, pagination, taxonomy, and other functionalities.

A typical Hugo front matter might look like this:

---
title: "Migrating from Obsidian to Hugo"
date: 2024-03-09
draft: false
tags: ["obsidian", "hugo", "migration"]
categories: ["Tech"]
series: "Obsidian to Hugo"
layout: "post"
weight: 10
aliases: ["/obsidian-migration"]
---

Some key differences include:

  • Taxonomies: Hugo expects tags and categories as predefined taxonomies, whereas Obsidian users might define their own (category vs. categories).
  • Publishing Controls: Hugo uses draft, publishDate, and expiryDate to manage visibility, which Obsidian does not enforce.
  • Aliases: Redirects in Hugo require an explicit aliases field, useful for handling old Obsidian note links.
  • Weight: Hugo uses weight for ordering pages within a section, something absent in Obsidian.

Mapping Obsidian Fields to Hugo

When migrating, you’ll need to adjust your Obsidian front matter to fit Hugo’s expected format. Here’s a structured approach:

1. Standardizing Taxonomies

If you use a custom category field in Obsidian, convert it to Hugo’s categories array format:

Obsidian:

category: "Tech"

Hugo:

categories: ["Tech"]

Similarly, if you use a custom topics field, map it to Hugo’s tags:

Obsidian:

topics: ["frontmatter", "migration"]

Hugo:

tags: ["frontmatter", "migration"]

2. Handling Custom Fields

Hugo allows custom variables, but they must be accessed through .Params in templates. If you have an Obsidian-specific field like custom_field, it will still be available in Hugo but must be referenced correctly.

Obsidian:

custom_field: "Some metadata"

Hugo:

custom_field: "Some metadata"

In templates, access it as:

{{ .Params.custom_field }}

3. Adjusting Date Formats

Ensure all date fields match Hugo’s expected format (YYYY-MM-DD or full timestamp YYYY-MM-DDTHH:MM:SS for scheduling content).

Obsidian:

date: 2024-03-09

Hugo:

date: 2024-03-09T00:00:00

4. Managing Content Organization

Obsidian relies on folder structures and note links, while Hugo expects content organization via front matter settings.

  • Convert Obsidian folders into Hugo sections.
  • Define aliases to maintain internal links from old Obsidian paths.

5. Automating the Migration

If you have hundreds of Obsidian notes, manually converting front matter isn’t practical. A Rust script can automate this transformation by reading YAML, adjusting field names, and rewriting the front matter to align with Hugo’s format.

A follow-up post will dive into writing a Rust-based conversion script to streamline this process.

Conclusion

Migrating from Obsidian to Hugo requires careful front matter adjustments to ensure content renders correctly. By understanding the differences and mapping your fields strategically, you can seamlessly transition your notes into a structured, publication-ready format. In the next post, we’ll explore a Rust script to automate these transformations efficiently.