How to blog from your phone using Hugo, Github and Obsidian

I have been blogging with Hugo for 3 years and am really happy with it. Not only does it liberate me from maintaining a CMS like Wordpress, I can also switch themes easily, employ robust source control via Github, and have fine-grained control of how things look with config files and small CSS/HTML tweaks.

Recently I want to create a new mini-blog for short-form content, e.g., thoughts I come up with when I’m on the road. For this scenario, I’ll usually jump to Obsidian, my trustworthy 2nd brain. But what if I want to share these thoughts with the world? Can I post to my Hugo blog using only my phone?

Yes, we can! By the end of this post, I’ll show you how to create and publish a new blog post with just 2 UX gestures (tap to create post, tap to push to github for CI/CD) with free phone apps. Ok….we do need to write something in between😊

Granted, the workflow wasn’t very straightforward initially, and I’ve spent nearly a day toying with multiple tools and processes until it works! This post will show you how so you don’t waste as much time as I did. I will call out all my mistakes with notes!

What we’ll do

Since we are essentially migrating our existing desktop workflow to mobile, I’ll assume that you already have the followings in your desktop environment:

A properly setup Hugo blog
Github account and a repository
Github Action setup to deploy your blog automatically on push

What we’ll do here is

Enable mobile editing and sync

We will install a mobile authoring tool. Pick one from these based on your need:
- Github Mobile app, for light authoring of text only
- Obsidian app, for authoring both text and images
Copy blog project to mobile, if using Obsidian. Setup Obsidian-Git plugin to sync.

With this in mind, let’s go!

Setup mobile editing and sync

Github Mobile app

Let’s set your expectation right. Github Mobile can perform the followings without issue

edit existing file including markdown
create a new text file. However, in our blogging scenario, you need to manually create new frontmatter which is a very tedious and error-prone task
manage workflows, PR request, etc.

If you want to add existing photos from your phone to the post, then you’re out of luck as the app doesn’t support it. After extensive research, I’ve seen people claiming that using a mobile browser to access Github.com, then request desktop site will reveal the magical “Add File” button where you can add a local photo to the repo. You can then link to it from your existing text file. Unfortunately, I’ve tried Edge, Chrome and Safari and none of their “request desktop site” will reveal this button in both landscape and portrait mode. All I can see are some grayed out or locked buttons!

Compare the true desktop site below

with this request desktop site from mobile browsers. There is no + button and the ... button circled by orange is disabled.

This then brings us to the next solution, which solve the frontmatter and image upload issue.

Obsidian

For people who journal or keep lots of notes, Obsidian is not a stranger. Now it proves its value beyond that.

Since both Hugo and Obsidian work on markdown files, we can just copy the whole blog project folder to our phone and have Obsidian open it as a vault. Then we can just create and edit .md files and add images to it as attachment!

With the obsidian-git plug-in, we can then sync with our Github repo and have the latter kick off auto deployment jobs with existing workflow Action files!

Mission accomplished!

Now let’s dive in the details.

Move blog to Obsidian

It’s ok if you do not have Obsidian installed in your desktop, as you can complete this process with only your phone. Just install the app from your mobile app store.

After installation completes:

Open Obsidian and tap Create a vault, skip sync for now, use test as the new vault name. Close Obsidian.
Go thru the following steps to copy your blog folder to local

A. If you are using Android
- connect your phone to your desktop
- locate the Obsidian folder in the phone
- copy the whole blog folder over
B. If you are using iPhone
- copy the blog folder to iCloud in your desktop. Verify that it has sync’ed.
- open the Files app in your phone
- tap Browse. In Locations, tap iCloud drive. Locate the blog folder
- long tap for the menu, choose Copy. Tap <iCloud Drive,<Browse, On My iPhone, locate the Obsidian folder and tap Copy. The blog folder will now reside in Obsidian folder.
  
  note: Why copy the folder locally instead of letting it reside in iCloud? There are 2 reasons
- 1. when you open the new Obsidian app and pick Use my existing vault and point to iCloud, it will complain that it does not detect a vault in iCloud because it is not stored on the top-level Obsidian folder. This happens even if you explicitly make an Obsidian folder in iCloud and copy the blog into it. This is a known issue: you can create a new vault in iCloud from the app, but cannot open an existing iCloud vault like in desktop.
  2. iCloud would periodically delete unused files in your phone to save space and would often lead to file conflicts and duplicates, especially if you are accessing the same vault in multiple devices. Since we are using Github to sync our files, it’s better to stick with one sync service.
Open Obsidian. It should show you a vault list with both the test vault and your blog. Tap your blog and Enter vault.
Tap the icon circled in red and you will have an explorer view of everything in your blog folder! open folder as vault explorer view of vault

Now we have our blog in Obsidian!

Time to do some clean up. Tap the vault name on the upper left of the Explorer view and tap Manage vaults… Tap the test vault we created earlier and select Delete vault to remove it.

Sync with Github

Obsidian opens the door to various helpful plugins. We will look at 3 in this post. First let’s take care of Github sync.

Let’s create a Personal Access Token to authenticate our Obsidian connection to Github. Go back to Github.com in your desktop. I cannot find the following options in my iOS app.

In the upper-right corner, click your profile photo, then click Settings.
In the left sidebar, click Developer settings->Personal access tokens. You can choose between a classic or fine-grained token. Let’s pick Fine-grained tokens.
Click Generate new token.
Give your token a name, set an appropriate expiration date, then click only select repository and pick your blog repository.
Expand Repository permissions and grant Read access to metadata, Read and Write access to actions, code, commit statuses, deployments, merge queues, pull requests, and workflows.
Click Generate token. Copy the value.

Now we are ready to setup on the Obsidian side.

Tap the upper-right gear icon in Explorer to open vault settings.
Tap Community plugins and turn off Restricted mode.
Tap Browse and search for git
Choose the one by Vinzent
Tap Install. When it is done, tap Enable.
Tap Options to configure the plugin. You will see all sorts of settings. But first we need to enable authentication to Github using the Personal Access Token we generated previously.
Scroll to Authentication/commit author. Enter your Github username and Personal Access Token. You must also enter author name and email for commit, otherwise the plugin will refuse any commit later.
Also make sure the pull settings are configured for more seamless sync

That’s it. Now we can go back to Explorer view. Open a post and do some editing.

Then tap the hamburger icon on the lower right corner to open Git source control.

You will see the following Source Control pane showing all the changes. Optionally, edit the commit message (underlined by red). Tap the upload icon (green circle), which combines stage, commit, and push into one action!

If you want, you can tackle each task in the following gesture: - Stage modified files: + icon - Commit changes: check icon - Push changes: upload icon - Pull updates: download icon

Upload images

Now let’s add images to our post.

Control how images are saved and linked

Just like Github Mobile, you cannot directly add an image to the blog folder. However, you can add it as an attachment to an existing file.

We can open an existing .md file, tap the clip icon to add a photo from our photo library, choose from the phone’s file folder or take a live photo. A link will be generated and the photo is automatically embedded in the .md file. (If you are curious, you can get the link by tapping the 3 dots on the upper right corner and tap Source mode).

We can control where the image is stored and how the link is generated in Settings/Files and links. Specifically, configure this section:

We will need to

turn off Use wikilink as Hugo needs properly formatted Mardown links to generate HTML files.
It depends on where you want to store the images. If you use Hugo page bundles, and want images to reside in the same folder as the blog post, choose
- New link format: shortest path when possible
- Default location for new attachment: same folder as current file
the catch for this approach is that some Hugo themes expect cover images to be in /static folder. With this setting, you will not be able to refer to these images. You can temporarily solve this problem by setting the Default location for new attachment to in the folder specified below and set Attachment folder path to static.

Any good alternatives?

Looking at the image upload scenario, what we really want is to upload an image from mobile, and get a direct URL to link from our posts. That begs the question, can we use something better?

CDN: I’ve tried free solutions such as ImageKit.io and Cloudinary. The former has no mobile website which makes it very hard to use. The latter’s Media Library section in mobile always errors out.
Cloud drive such as Google Drive, iCloud and Dropbox: all provide a link to an embedded interface, not a direct link to jpg or png. This requires manually editing to strip out part of the URL. And Google/iCloud links are temporary with expiration date.

Obsidian Templates = Hugo archetype

This is definitely a bonus over Github Mobile.

Since we cannot run commands such as hugo new posts/mypostmd with Hugo’s archetype in mobile, we can instead take advantage of Templates and Unique note creator, both core plugins in Obsidian.

Templates is like archetype, whereas Unique note creator will create a new post with unique filename. When chained together, they streamline the whole post creation workflow with only 1 click.

First, create a post template called draft.md with the following frontmatter to automatically create frontmatter. Using {date}T{{time}} will also fill in the post date with Hugo's approved date format. Store it in a new /template folder in the vault.

---
title: 
date: {{date}}T{{time}}
description: 
draft: true
image: 
imageAltAttribute: 
categories: []
----

Now let’s configure both plugins.

Tap the gear icon in Explorer, and tap Core plugins.
Enable both Templates and Unique note creator.
Tap the icon next to the slider
- Templates:
  - Template folder location: /template
  - Date format: YYYY-MM-DD
  - Time format: HH:mm:ss
- Unique note creator
  - New file location: content/posts
  - Template file location: template/draft
  - Unique prefix format: YY-MM-DD-H

Now just tap the hamburger menu on lower right and choose Create new unique note. In just 1 click, a new note named with today’s date and time will be created in my posts folder with the right frontmatter.

Write and publish

Now let’s test our process in the freshly created post:

let’s uncheck draft in frontmatter
add a new photo to it
tap hamburger icon to open Git source control
We notice a list of pending changes which shows the plugin has picked up our new file and edits automatically
Tap Commit and Push
Open Github Mobile and go to our blog repo. Tap Actions. We should see that a new workflow has been triggered.
After the job finishes, hit your public site and enjoy the changes!

Final Thoughts

I’m glad to have the flexibility of using a lightweight tool such as Github Mobile when I just want to dictate or write a short blurb. Or I can jump back to Obsidian for a more author-centric environment that offers rich features such as graph view, backlinks, templates, outlines, etc. I think there is an additional opportunity to use Obsidian with Hugo to create a digital garden using a doc theme, while employing the draft property in frontmatter to control what goes public or not. In this way, I can easily combine both my private journal with public-facing notes and blog posts in a single vault to streamline my workflow and maintenance.