↓ Skip to main content

Hugo Compose: a CMS That Fits in One File

·739 words·4 mins
David Smith
Author
David Smith

I’ve been running this site on Hugo for a while now, and the one thing that’s always been slightly annoying is publishing from my phone. Hugo is a static site generator — it expects you to write Markdown files, commit them to Git, and wait for a build pipeline. That’s fine at a desk. It’s less fine when you’ve taken a photo you want to post and you’re standing in a car park.

So earlier this year I built a PWA to solve it. It lived at /compose/ on this site, and it let me write blog posts and photo posts from my phone, complete with image resizing and tagging, and commit them directly to GitHub. One tap and the deploy pipeline picks it up. It worked well enough that I stopped thinking about it, which is roughly the highest compliment you can pay a tool.

This week I pulled it out of my site, made it generic, and open-sourced it.

What it is
#

Hugo Compose is a progressive web app — a single index.html file, about 120 KB — that you drop into your Hugo site’s static/ directory. Once deployed, you open it on your phone, add it to your home screen, and it runs as a standalone app with offline support. Configure your GitHub username, repo, and a Personal Access Token in settings, point it at your content directories, and you’re done.

It creates proper Hugo page bundles: a directory with index.md and your images alongside it, committed in a single atomic Git commit via the Trees API. Your existing CI/CD — GitHub Actions, Netlify, Cloudflare Pages, whatever you use — picks up the commit and deploys.

What it does
#

Photo posts: pick photos from your camera roll, write a caption, add tags with hashtags. The app resizes images to JPEG (max 2000px), names the first one feature.jpg, numbers the rest, generates the front matter, and commits the whole page bundle.

Blog posts: a Markdown editor with a formatting toolbar — bold, italic, headings, links, lists, quotes, code — plus optional images and a draft toggle.

Offline drafts: write when you have no signal. Drafts are stored in IndexedDB with the full image data and sync when you’re back online.

Configurable everything: posts path, photos path, front matter format (TOML or YAML), branch. If your Hugo site uses content/blog/ instead of content/posts/, just change the path in settings.

What it doesn’t do
#

There’s no backend. No account. No sign-up. No server holding your content or your credentials. The GitHub token lives in your browser’s localStorage and goes nowhere except the GitHub API. Images are processed entirely client-side.

It also doesn’t try to be a full CMS. You can’t manage your Hugo config, edit your theme, or reorganise your content tree. It does two things — photo posts and blog posts — and it does them from your phone in about thirty seconds.

The iOS bits
#

A surprising amount of the work was making it behave properly on iOS. Safari’s PWA support has opinions:

  • The soft keyboard pushes the layout viewport up but not the visual viewport, so the app uses the visualViewport API to pin the UI correctly.
  • Textarea auto-grow has to be grow-only — if you reset the height to measure the content, iOS fires spurious input events that cause an infinite loop.
  • iPad with a hardware keyboard doesn’t trigger the soft keyboard detection, so it uses natural CSS flex instead of the JS resize hack.
  • Safe area insets for the notch, the home indicator, and landscape mode.

None of this is documented anywhere useful, which is roughly why I’m open-sourcing it rather than keeping it to myself.

How to use it
#

  1. Copy the files into static/compose/ in your Hugo site
  2. Deploy
  3. Open /compose/ on your phone, add to home screen
  4. Configure your GitHub token and repo in Settings
  5. Post things

Full setup instructions and documentation are in the README.

What’s next
#

There’s a native iOS version in the works that will add Share Sheet support (post photos directly from the Photos app), background uploads, and a proper native photo picker. The PWA will stay as the zero-install option for anyone who wants to drop a single file into their Hugo site and start posting.

The code is MIT-licensed. If you use Hugo and you’ve ever wanted to post from your phone without opening a laptop, give it a try.