How I Built the Blog
A short guide outlining how I built this blog using Obsidian, Hugo, Github, and Cloudflare.
This builds on some of the excellent things posted by various folks previously, the initial inspiration for this came from Vashul Agwaral, which lead me down the rabbit hole of various other useful bits and pieces listed below:
The blog currently uses the excellent bilberry-hugo-theme to make it look nice.
Normally I would have gone down the github pages route to host this, but I’ve recently been building something else (that warrants a whole other post at some point) and really started to get into all the functionality Cloudflare offer on their free tier. That’s also one of my main criteria for all of this, everything is free.
Obsidian
Because I use Obsidian as my main “second brain” for both work and personal stuff this is the logical choice for me as the primary interface to create the content. I also wanted to be able to keep the Vault as a separate entity outside of the main repo eventually, this will allow me to edit the contents across all of my devices as I do with my main personal Vault, but for now it’s just a separate folder in the repository, I’ll do the separation later.
Markdown conversion
Obsidian can be setup to mostly produce vanilla Markdown, but I wanted to just use Obsidian as I do normally so needed to find something that would take the Vault contents and produce consistent vanilla Markdown. Doing this allows some flexibility in the future as vanilla Markdown gives a consistent jump off point to explore using different static site generators and frameworks that Cloudflare supports
Hugo
I’d never come across Hugo before I started down this rabbit hole, the main one I was aware of was Jekyll as that’s the one preferred by Github. Hugo seemed interesting and I found some tools to do the Obsidian to Hugo conversion so went with that. I think it’s probably worth taking a look at Obsidian to Jekyll at a later date to see how that compares.
Workflow
At a very high level the workflow looks like this
This workflow evolved as I was building it allowing me to remove quite a few of the transitional folders from the final git repo. What I ended up with was the main Obsidian Vault, some Hugo config for the site, and a couple of bits of static content. So the only thing that needs to change is the content of the Obsidian Vault and everything else after that is generated.
I’ve created a template repo for anyone who wants to play along at home, this contains everything used to produce this blog apart from the content in the vault folder and the config in the config/_default/hugo.toml file. The key part of the repo that ties everything together is the Makefile which contains targets to make life easy.
So my workflow goes like this when I want to create a new blog post:
make article.MyNewBlogPost- change MyNewBlogPost to the name of the folder to create in the Obsidian Vault.
- Open the
vaultin Obsidian and edit the post make server- to start the local webserver, I do this in a new terminal.- Note: this runs the local server to expose all draft posts as well
make browser- opens a web browser pointing at the local site- I keep hacking away at the blog post and run
make obsidian-exporteach time I want to refresh the local content to see how it looks.
When I’m happy with the post, I change the front matter to be draft: false and push the updates to the Git repo, this is then picked up by Cloudflare and deployed. Essentially it runs make production and deploys the contents of the resulting public folder. I’ll cover this in more detail in a future post in this series.
Hosting
Currently the blog is hosted on Cloudflare Pages which has a hook into updates to my Github repo for the site, but there is no reason it couldn’t be hosted on one of the many free static site hosting options, e.g. github pages or Firebase Hosting, it would just need the a build runner configuring to checkout the repo, run make production, and deploy the public folder to the correct location. Github Actions feels like the most logical option for this right now.
Conclusion
Overall I’m happy with how this has come together in the end, I like the flexibility it gives me to choose different hosting providers and static site generators while maintaining the core experience of writing everything in Obsidian. There are some improvements still to come, the main one I think is to figure out a way to separate the vault out to Google Drive so I can edit things on any of my devices.