Dr. Jeff Avery / Publishing Obsidian Notes

Over the past few years, I’ve moved through a number of solutions while figuring out how to publish courses notes online. Currently, I’m publishing with Hugo, which is an exceptionally great tool for small sites.

Authoring in Hugo

However, authoring notes for a Hugo website isn’t great. Hugo represents each page as a folder containing a index.md file. The file contains a YAML header for metadata, and markdown content for the body of that note:

+++
title = "Outline"
menuTitle = "Outline"
disableToc = false
alwaysopen = false
tags = ["syllabus"]
weight = 1
+++

## Course Description
From the [course calendar](https://ucalendar.uwaterloo.ca/2223/COURSE/course-CS.html#CS346):

> **CS 346 LAB,LEC,TST 0.50**
> **Application Development**
>
> Introduction to full-stack application design and development. 

This is exported to HTML by Hugo, with the appropriate transformations. This mapping from MD to HTML adds a few complexities related to editing and authoring:

• Adding a note requires creating the appropriate directory structure, and YAML header before you can start adding content. This is a significant barrier to quickly adding content.
• Links between notes need to be done using the relative URL of the notes as they will appear on the website. Because of the way that Hugo structures content, the directory structure and export structure do not necessarily match so this can be tricky.
• Theme features like admonitions are specific to Hugo, so their syntax isn’t recognized in an editor. e.g. the Hugo RELEARN theme supports additional features (aka shortcodes) that no editor supports directly.
• Customizing the site requires significant work to understand and modify a theme.
• It’s fragile. I’ve had themes stop working over time due to update issues.

Enter Obsidian

I recently moved to [[https://obsidian.ms|Obsidian]] for local notes. That worked so well that I migrated most of my notes from Hugo to Obsidian, and published this site using [[https://obsidian.md/publish|Obsidian Publish]].

From the perspective of authoring notes, what do I like?

• Obsidian client and publishing site are run by the same company, so there are no compatibility/versioning issues. It’s a lot more stable than publishing with Hugo, which has many different dependencies that can break.

• Export is built-into the Obsidian client, so no additional scripts to write or maintain.
• Notes are just plain markdown files, with no required metadata (i.e. it’s optional).
• There are some additional markdown features that Obsidian supports, but they are supported on the publishing site as well e.g. image resizing ¹.
• Structure is interpreted from the directory structure. The input folders and output structure match completely so there is no effort required when creating new notes.
• The built-in theme is excellent, and offers features like full-site search, light-dark mode and so on.
• I can add favicons, custom CSS to easily add site customizations.
• Excellent documentation.

It’s a paid service, but especially with an educational discount, it’s a very reasonable cost and well-worth the benefits. For me, it’s completely removed the friction of writing: I can just write a note and hit publish and it’s done.

Publishing Notes

So how does it work?

1. Create a new Obsidian vault.
2. Create a folder structure and markdown files that reflect the structure you want.
3. Install and enable the official Publish plugin.
4. Run Command > Publish, and provide login details and publishing details from the popup screen that appears.

When you want to publish content, just run Command > Publish and select the files to synchronize. It’s very fast and efficient.

Alternatives?

I love Publish and I expect to stick with it. However, I now have 2 sites:

• A Hugo site for my course website, where I maintain the Hugo file and folder structure.
• A Publish site for all of my other notes, that I publish to from Obsidian.

The “easy” solution would be to host course website on publish as well, but I’d like to avoid the hosting cost for a simple static website. It’s also important to keep official course content on University hosted websites.

I’m currently considering Quartz 4.0 as an alternative that might let me publish to a self-hosted site from Obsidian.

I have hit a feature restriction that might prevent me from using Obsidian Publish for everything: it doesn’t allow you to upload arbitrary (unrecognized) file types. For example, I can upload images that are used by one of my pages, but not a ZIP file that I want to make available. I’ve gotten around this in one case by hosting the ZIP file on a different site and linking it, but that’s not ideal either.

This isn’t an issue with Hugo, so it may be a deal-breaker for course websites.

#obsidian #markdown