Exploring Obsidian: Crafting and Publishing Posts with Hugo

As I state in the about page, I love markdown and I always wanted to make a giant repository, a second-brain or anything that could aggregate knowledge, links, random notes etc.

Few years ago I jumped from Apple Notes to Notion, which I loved for a while. I was always hating the fact it still is purely server-based, meaning:

Your notes are in an S3 instance somewhere, with no direct access;
Cannot be self-hosted;
There is no offline sync. No internet access = cya notes.

Last year, during CloudFlare’s major outage Notion was impacted too. At that time I found out as I had to write a meeting summary, and during that meeting I took notes that were stuck in Notion.

For me (and part of the Notion community) it was the cue to finally switch to something else, and Obsidian was the perfect choice:

All the files are structured in a “Vault” that is no more than a directory;
All the files are in pure markdown, meaning that any text editor could open them.
You can choose to sync your notes with their service, or use whatever sync service you want. Since some of my devices are Apple, i use iCloud Drive to sync them, and Duplicati to save a backup to my server.
There are community plugins which automate and extend this application in all the way possible.

One of them is Obsidian Publisher which I use to draft posts like this on Obsidian and upload them to my website in one click. All you need is a GitHub repository and a frontmatter to let the plugin know if a note is a post.

Here’s a small guide on how to setup everything:

Prerequisites

Git
Go
Hugo

Create a Hugo website

There are tons of guides around this subject. I personally recommend reading Nuno Coração’s guide to setup a good environment, though my personal setup differs a little, still using Docker as development container.

Assuming you have everything installed correctly, create a folder, then open a Terminal inside it:

hugo new site my-hugo-website

then, create some content by running:

hugo new posts/my-first-post.md

Then, you can test your site locally by running hugo server -D, then open your web browser and go to http://localhost:1313 to preview your site.

Create a GitHub Repository

Create a new GitHub repository based on your hugo installation. Your directory hierarchy should be like this:

example/
├── archetypes/
│   └── default.md
├── assets/
├── content/
├── data/
├── layouts/
├── public/
├── static/
├── themes/
└── hugo.toml

You might want to name it mywebsite.github.io if you want to use GitHub Pages as hosting platform, where mywebsite is your website name.

Download Obsidian GitHub Publisher

In your Obsidian’ settings, you should find “GitHub Publisher” by searching it in the Community Plugins tab.

Setup GitHub Publisher

In Settings, find the following tabs into the plugin settings. There is a lot of options you can tinker around with, but these are essential:

GitHub Configuration

Put in your Repository Name, GitHub Username, and GitHub Token (you can generate it here), then the main branch (might be “main” or “master”)
Test the connection

Upload Configuration

Choose how you want the file tree to appear. I like to use “Obsidian Path”

Tag your posts and upload

You can then mark the post you want to publish with the share: true frontmatter, plus other that are used by Hugo. If everything is set up correctly, you can use the command palette ⌘ + P to invoke the “GitHub Publisher: Upload all shared notes” command. Then, a PR is created and the markdown files are pushed to your repo.

Extra: Build with GitHub Actions

In my case, here’s what is triggered when the content is pushed to the repo . I created a /.github/workflows/deploy.yml file with the following instructions:

name: Deploy website via FTP

on:
  push:
    branches:
      - master

jobs:
  deploy:
    runs-on: ubuntu-latest
    environment: secrets

    steps:
      - name: Checkout code
        uses: actions/checkout@v3
        with:
          submodules: true
          fetch-depth: 0

      - name: Install Hugo
        uses: peaceiris/actions-hugo@v2
        with:
          hugo-version: "0.107.0"

      - name: Install lftp
        run: sudo apt-get install lftp

      - name: Build Hugo website
        run: hugo --minify

      - name: Upload files via FTP
        env:
          FTP_SERVER: ${{ secrets.FTP_SERVER }}
          FTP_USERNAME: ${{ secrets.FTP_USERNAME }}
          FTP_PASSWORD: ${{ secrets.FTP_PASSWORD }}
          FTP_DESTINATION: ${{ secrets.FTP_DESTINATION }}
        run: |
          lftp -c "set ftp:ssl-allow no; open -u $FTP_USERNAME,$FTP_PASSWORD $FTP_SERVER; mirror -R ./public $FTP_DESTINATION"

So basically the workflow is:

Checkout the code with submodules
Install Hugo
Install lftp
Build the Hugo Website (minified)
Upload the files via FTP to my server, using Environment Secrets

And that’s how I can draft and publish posts in one click.

Have fun!

P.S Most of the knowledge I have on Obsidian’s community plugins sources from a talk that I had with my good friend Kyles who is an absolute Obsidian Guru. Props to him.

2023-08-17

../