Using Pages CMS as a Backend for HUGO Blog

After migrating from WordPress to Hugo, I have always missed the convenience of WordPress’s backend management and its mobile app. For this reason, I previously wrote an article on How to Update a Hugo Blog on an Android Phone. However, using Vscode and StackEdit on a phone is still somewhat cumbersome, mainly due to the small screen size, which makes fine-tuned operations difficult with touch controls. During this process, I also tried several Hugo CMS solutions, but none met my needs.

Several Failed Attempts

Decap CMS

Decap CMS, formerly known as Netlify CMS, is closely associated with Netlify, as the name suggests. Its default deployment method is on Netlify, but since I couldn’t register a Netlify account, I put it on hold. Later, I discovered that Decap also has a server deployment version, so I tried it on an Oracle VPS. Although the installation was successful, there were still a bunch of Hugo adaptation settings that seemed too complicated, so I didn’t proceed further.

Decap CMS

QUIQR

QUIQR is a localized software that can be directly installed on Windows. However, it does not support a web version or a mobile app, which means it cannot be used on a phone. This does not align with my intended purpose.

Quiqr CMS

Tina CMS

Tina CMS, formerly known as Forestry CMS, is another headless editor. However, I had no luck with it. Even though I set up a Tina Cloud account and added a project, I was stuck on the local Tina installation. I don’t know if it was due to my network issues or something else, but I couldn’t successfully install the Tina program on two different computers. Then, I found a Vercel deployment version, but during the deployment process, I discovered that the Vercel one-click installation template provided by Tina seemed outdated, and I couldn’t deploy it successfully on Vercel after much effort. Finally, with the help of AI, I downloaded a bunch of Python, C++, and Win10 SDKs, and finally managed to install Tina. However, it still had issues, particularly with handling image links. I will explain this in detail later, as it is the same issue with Pages CMS.

Tina Installation Failure

Sveltia CMS

Sveltia CMS is another CMS recommended by Hugo, serving as an alternative to Netlify/Decap CMS. The developer mentioned that version 1.0 will be released in 2025, and the current version still requires setting up Netlify/Decap CMS first. Since I don’t have a Netlify account, I can’t proceed with it for now.

Important Note The issues mentioned in the following content have been resolved in another article: Configuring Pages CMS to Match Hugo’s Directory Structure.

Pages CMS

Pages CMS is a new open-source project on Github. In its 0.x version, you could choose to deploy it quickly on Cloudflare. Recently, it upgraded to version 1.0, which defaults to deployment on Vercel. I tried the 0.x version before, and the main issue at that time was that the CMS did not support webp images. I submitted an issue on the project, and this morning I received a reply from the developer saying that the latest version has resolved this issue.

Excitedly, I followed the documentation to deploy the 1.0 version. The process was relatively complex but went smoothly. However, during usage, I encountered an issue that I couldn’t resolve: Unable to Resolve

My Hugo blog files are all in individual folders under content/posts, with blog images and md files in the same folder. I managed to solve the issue of uploading and referencing images in the body text, but the featured image address automatically generated in the front-matter couldn’t be rendered by Hugo.

So, I submitted this issue to the developer. However, the developer also mentioned that he couldn’t solve it for now, and several others had raised similar issues, all stuck on Hugo’s file paths.

After seeing the developer’s reply, I almost gave up on the idea of continuing to use a CMS.

Developer
It’s been asked a few times for this (for Hugo specifically). I’ve not yet figured out a way to handle this gracefully in Pages CMS. The expectation right now is that you upload all media in the same folders, not individual folders for your content.

Me
Thank you, I’m completely heartbroken. I’ll just keep using some IDE tools like VSCode, but it’s really inconvenient on a phone.

Developer
Doesn’t mean I won’t get something sorted out ultimately. I just need time to sit down and figure out how I would handle it. The main issue with this Hugo flow is that you need to define the name of the folder (and thus the slug) before you upload the assets. But in Pages CMS, for new entries, the slug/filename is set up on saving the entry. If you have suggestions, let me know.

After seeing the developer’s reply, I suddenly thought, why should the Hugo featured image path be converted by the CMS? I can just input the path directly.

Original Solution: Using Pages CMS Automatic Conversion

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
media:
  input: content/posts
  output: /content/posts 
content:
     ...
      - name: image
        label: Image
        type: image
        list: true
        options:
          input: content/posts
          output: /content/posts

New Solution: First Set Up an Image Upload Area, Then Manually Input the Featured Image Address

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
media:
  input: content/posts
  output: /content/posts 
content:
     ...
      - name: uploadimage
        label: Uploadimage
        type: object
        list: true
        fields:
          - name: newimage
            label: newimage
            type: image
            options:
              input: content/post
              output: content/post
              categories: [image]
      - { name: image, label: image, type: string, required: true }

This way, at least the issue of Hugo’s featured image path error is resolved. However, it also brings a new problem: in the Pages CMS backend, you can’t see the image content in the text editing area. After using the ![](image.webp) syntax, the image directly disappears in the editing area. After adding the image name, it’s slightly better, as you at least know there’s an image in that position.

Display Error but Doesnt Affect Usage

If you directly use the / shortcut in the backend to call up the image function in the editor to add an image, although you can see what the image looks like in the editor, Pages CMS will automatically match the image path to /content/post/articl-pyth/image.webp, which is also unusable, as the image will definitely break after Hugo builds.

But in any case, I finally managed to set up a CMS backend that can be used with Hugo.

Solving the Image Breaking Issue

I found several similar issues in the Pages CMS project, but none were resolved. So, I had to turn to my old friend—the Hugo official forum.

On the Hugo forum, the person who answered my question was the same old comrade from Seattle. Unexpectedly, after his repeated inquiries, I finally found a workaround. Just change one thing: remove the content from the original image output path.

1
2
3
media:
  input: content/posts
  output: /posts 

However, this method is not perfect and still has two loopholes.

You need to set the article Slug to match the folder name to ensure consistency. This is because Pages CMS processes the image path based on the folder path, while Hugo processes the image link based on the custom Slug.
Images inserted this way can only display the original image. They won’t be processed by Hugo to generate images suitable for various screen sizes.

Github Modification for Automatic Deployment

Unlike StackEdit, which allows manual pause of synchronization, programs like Page CMS will submit updates to Github every time you save the .pages.yml file, upload an image, or save an article. This causes Github Actions, Cloudflare Pages, Vercel, and other automatic deployment services to continuously consume deployment time in the background. I thought creating a test branch would avoid this issue, but during the debugging of the .pages.yml file, Vercel was triggered over forty times for automatic deployment. I feel like if this continues, my account might get suspended.

Vercel Frequent Deployments

Vercel Ignore Deployment Settings

In Vercel Setting Git, there is an option to ignore builds. Select custom and add the following command.

1
if git log -1 --pretty=%B | grep -iqF 'webp'; then echo "🛑 - Build cancelled (commit message contains 'webp')"; exit 0; else echo "✅ - Build can proceed"; exit 1; fi

Principle: When adding images in Page CMS, Page CMS will automatically generate a commit message like Create content/editor/2024-12-07-pages-cms-a-barely-adequate-backend-for-hugo-blog/6.webp (via Pages CMS), where the keyword is the image format. Therefore, in the Vercel ignore build command, as long as the commit message contains webp, the deployment will be ignored. However, this setting has other indirect effects. The good thing is that you can write webp in the message whenever you don’t want automatic deployment; the bad thing is that you better not have webp in the file path, otherwise, you’ll have to deploy manually.

Github Actions Ignore Deployment Settings

Using the same principle, add the following code in the Workflow deployment template to detect if only webp images are submitted. If so, do not start the automatic build. My workflow is set to deploy from the Github repository to the VPS, and it works quite well. Normally, it takes a few minutes, but now it stops automatically in about ten seconds. However, this method seems ineffective for deploying to Github Pages, mainly because by the time the workflow detects the command, the build is almost done, and the remaining deploy to github pages only takes a few seconds, with most of the time spent on the previous steps.

1
2
3
4
5
6
7
8
9
- name: Check for non-WebP images # Add in build
        id: check_images
        run: |
          if git diff --name-only HEAD^ | grep -vE '\.webp$' > /dev/null; then
            echo "Non-WebP images detected. Proceeding with deployment."
            echo "::set-output name=deploy::true"
          else
            echo "Only WebP images detected. Skipping deployment."
            echo "::set-output name=deploy::false"

fi if: steps.check_images.outputs.deploy == ’true’ # Add in deploy

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12

![Effective Deployment to VPS](7.webp)

3. **Cloudflare Pages Ignore Deployment Settings**

No suitable method has been found yet. However, Cloudflare is financially strong and may not mind building a few more times.

* * *

## PagesCMS Settings

Finally, I am uploading my own PagesCMS configuration file for reference (a dedicated editor folder is created to publish content written by Pages CMS).

media: input: content/editor output: /editor categories: [image] content:

name: editor label: Articles type: collection path: content/editor filename: index.md view: fields: [ title, date, draft ] fields:
- { name: title, label: Title, type: string, required: true }
- { name: draft, label: Draft, type: boolean, default: true }
- { name: slug, label: Permalink, type: string, required: true }
- name: date label: Date type: date options: format: yyyy-MM-dd’T’HH:mm:ss time: true
- name: categories label: Categories type: select list: true options: values: - Life - Moments - Law - IT & Internet - Society
- name: tags label: Tags type: string list: min: 1 max: 6
- name: imageupload label: Photo Upload Area type: object list: true fields:
  - name: addimage label: Add Photo type: image options: input: content/editor output: /content/editor categories: [image]
- { name: image, label: Featured Image URL, type: string, required: true }
- { name: body, label: Body, type: rich-text }