It all started with the idea of publishing a blog post from my phone.
If you search my blog with “Hugo” as the keyword, you’ll find four or five articles discussing the same topic: how to publish a blog from a mobile phone.
This wasn’t my first attempt. Every time I had a writing inspiration while waiting for work, waiting for my child to finish school, or at home in the evening, I wanted to open my phone and update the blog. But then I’d think, “Forget it, I’ll have to open the computer,” or “I’ll have to make edits after uploading anyway, might as well do it tomorrow,” and just give up.
Anyone who uses Hugo knows the content itself isn’t the problem—Markdown can be written anywhere. The problem is how to handle images and how to publish after writing.
Why Hugo?
Hugo’s official tagline is “The world’s fastest static site generator.” This isn’t just marketing; it’s the real user experience. This blog currently has over 400 articles and more than 2,000 images, and each local build takes only 10-20 seconds. Compared to other static site generators, this speed is in a league of its own.
More importantly, Hugo’s consistent build speed and clean file organization give me zero motivation to switch to any other platform.
The Obsession with Integrated Text and Images
As an old-timer in IT who came from the WordPress era, I have deep-seated trauma regarding the “separation of text and images.”
Early WordPress didn’t have a built-in image library. To add images to articles, you had to find your own image hosting and use external links. Back in the day, I used Weibo, Flickr, Photobucket, Renren… Later, these services either shut down or stopped allowing hotlinking, turning all the image links in my articles into red X’s. Want to get them back? No chance.
So when I switched to Hugo later, what I appreciated most was its bundle mode: one folder per article, with the Markdown file and images placed in the same directory. When publishing, the entire folder is moved; images stay with the article forever—no loss, no mess.
This is, in my opinion, the ideal way to manage text and images. Bar none.
The Pain Point of Integrated Text and Images
Of course, I know that placing images in the article directory increases the GitHub repository size.
This issue is especially prominent on mobile—nowadays, a single phone photo can easily be 10MB. If you try to publish an article using the GitHub App on your phone, just uploading the images can bloat your repository.
In 2024, while optimizing my blog, I made a firm decision: convert all images to WebP format. Now my blog has about 2,000 images across 400+ articles, and the entire repository is only around 100MB. For most individual users, this solution is entirely practical—it retains the convenience of integrated text and images without causing repository explosion.
The Methods I’ve Tried Over the Years That Weren’t Great
Back to the issue of mobile publishing. Since Hugo is so good, are there ready-made solutions for writing and publishing articles from a phone?
The Official GitHub App
The most straightforward idea. The result? The app is mainly for code collaboration; the Markdown writing experience is at a “barely usable” level. What’s even more troublesome is adding images—photos taken with a phone are often 10MB+. Uploading them directly to the repository is simply not feasible. You have to compress them first, then upload, then paste the links into the article. Going through this entire process is more troublesome than doing it on a computer.
GitHub Issue Workflow
I once researched a specific solution: using GitHub Issues as a publishing entry point, with Actions automatically converting Issues into Hugo articles. I wrote an article detailing the implementation: Publishing a Static Blog via GitHub Issue (in Chinese). Feel free to check it out if interested.
At that time, I felt I had reached the “endgame” for “publishing Hugo from a phone.” I used GitHub Actions to automatically fetch issue content and custom label formats to extract Frontmatter information. But in practice, it felt “not formal enough.” I had to remember various settings in the workflow, and I actually used it very little—only twice since that article.
Headless CMS
I tried solutions like Netlify CMS, Pages CMS, and others. The experience was indeed better than the GitHub web interface, with editors and image management.
But they all had a fundamental problem: separation of text and images. The design logic of these CMS platforms is to manage “articles” and “images” separately—articles stored in one repository, images in another asset library, linked together via URLs in the end.
Even if you managed to configure it successfully, there were usage issues. For example, images wouldn’t display in the editor.
This inherently conflicts with Hugo’s bundle mode. You publish an article in the CMS, images get uploaded to a remote image library, and Hugo’s rendering gets all messed up with the paths. It’s not that the CMS is bad; it’s just incompatible with Hugo’s design philosophy.
Temporary Solutions
I’ve also used several temporary solutions, like CodeServer (a browser-based VSCode) and online editors like StackEdit. In fact, this time I initially wanted to fork and modify StackEdit to adapt to Hugo’s default upload paths. But during the modification process, I found the project was too old with many outdated dependencies. Moreover, the project itself was quite large, making modifications less efficient than building something new from scratch.
And thus, Pocket Hugo was born!
What Pocket Hugo Solves
- Browser-first, open and use
No need to download an app or configure complex environments. Phone, tablet, desktop—open a browser, log into GitHub, and start writing.
- Respects Hugo’s bundle mode
Supports three content structures:
• Flat Markdown: Traditional single file
• Single-language Bundle: One folder per article, containing index.md + images in the same directory
• Multilingual Bundle: Multi-language versions
Maintains Hugo’s original directory structure. No need to change writing habits to accommodate the tool.
- Automatic image compression before publishing
Take a photo with your phone and upload directly. The system automatically compresses and converts to WebP; no manual image processing required. This retains the convenience of integrated text and images without bloating the repository.
- Drafts saved in the browser
Didn’t finish writing halfway through? Open it next time and continue. No content loss due to interruptions.
- Zero server-side storage
All data stays in the browser. The server doesn’t store tokens, articles, or any user data. Use it and leave; no traces remain.
Ready-to-Use Online Version:
• Entry: https://leftn.com
• Guide: https://leftn.com/guide
Self-deployment is also simple, with documentation available for Vercel or Cloudflare Workers.
Open-source project address: https://github.com/h2dcc/pocket-hugo
If you’re also struggling with Hugo mobile publishing, feel free to give it a try. Any issues are welcome as GitHub Issues, and stars are appreciated too.