Last year, I wrote an article titled Publishing Hugo Blogs on Mobile Using StackEdit, but I haven’t used it much since then. The main reason is that I rarely update my blog on my phone, and I also found another excellent tool called PageCMS (see: Using Pages CMS as a Hugo Blog Backend). However, overall, smoothly updating a blog on mobile remains quite troublesome, so some adjustments to the original method are necessary.

Previous Main Issues

1. StackEdit Problems

   • The primary issue was with image uploads. By default, Hugo places images in the same folder as the index.md file, but StackEdit uses a gallery mode, requiring images to be uploaded to a single designated folder, which disrupts Hugo’s directory structure.
   • Additionally, StackEdit operates on a local cache + online sync model, which generates many cache files during synchronization. The high default sync frequency also puts pressure on repository management.

2. PageCMS Problems

   • The editor has poor touchscreen support on mobile, whether using the rich text or Markdown editor, making it prone to glitches.
   • Since PageCMS adapts to Hugo’s directory structure by modifying Hugo’s template image hooks, the uploaded image paths don’t match Hugo’s rendered paths. As a result, images may appear broken in the backend editor.

3. VSCode Problems

   • I previously used the web version of VSCode for writing, but its biggest drawback is its poor touchscreen support. Text editing is cumbersome, making even basic operations like copy-paste difficult on mobile.

Improvements

For mobile writing, the usability of the Markdown editor is paramount. In this regard, StackEdit naturally outperforms the other options. As for the earlier issues, I realized they could be mitigated with some adjustments.

Repository Sync Setup

Instead of directly opening the Hugo repository in StackEdit, I switched to syncing specific directories via Rsync.

For example, the following workflow ensures that only updates with the commit message “new article” are automatically synced to the Hugo posts directory. This prevents unintended changes to the Hugo directory when experimenting in StackEdit, effectively acting as a manual commit mechanism.

1. Create a Personal Access Token

• Go to GitHub Settings → Developer settings → Personal access tokens.
• Generate a new token (enable repo and workflow permissions).
• Save the token (needed later).

2. Add Secrets to the Source Repository

• Navigate to the stackedit-app-data repository’s Settings → Secrets.
• Add TARGET_REPO_TOKEN and input the generated token.

3. Configure GitHub Action in the Source Repository

• Add the following sync workflow to .github/workflows/sync.yml:

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52

name: Conditional Sync Editor Content  

on:  
  push:  
    branches: [master]  
    paths:  
      - 'content/editor/**'  
  workflow_dispatch:  # Allows manual workflow triggering  

jobs:  
  sync:  
    if: contains(github.event.head_commit.message, 'new article')  
    runs-on: ubuntu-latest  

    steps:  
      - name: Checkout source repo  
        uses: actions/checkout@v4  
        with:  
          path: 'src'  # Explicitly specify the checkout directory  

      - name: Prepare target repo  
        env:  
          TARGET_TOKEN: ${{ secrets.TARGET_REPO_TOKEN }}  
        run: |  
          git config --global user.name "xx" # Replace with your main account  
          git config --global user.email "xx@live.com" # Replace with a verified email  
          git clone "https://oauth2:${TARGET_TOKEN}@github.com/h2dcc/lawtee.github.io.git" target-repo  
          cd target-repo  
          git pull origin master  

      - name: Debug directory structure  
        run: |  
          echo "==== Source Directory ===="  
          ls -lR $GITHUB_WORKSPACE/src/content/editor  
          echo "==== Target Directory ===="  
          ls -lR $GITHUB_WORKSPACE/target-repo/content  

      - name: Sync files with rsync  
        run: |  
          rsync -av --delete \  
            --exclude='.git' \  
            --exclude='.github' \  
            $GITHUB_WORKSPACE/src/content/editor/ \  
            $GITHUB_WORKSPACE/target-repo/content/editor/  

      - name: Commit & Push  
        run: |  
          cd target-repo  
          git config --local user.name "xx"  # Replace with your main account  
          git config --local user.email "xx@live.com" # Replace with a verified email  
          git add -A  
          git diff --quiet && git diff --staged --quiet || (git commit -m "Auto-sync: ${{ github.event.head_commit.message }}" && git push origin master)  

Image Path Handling

Image management in StackEdit is a bit tricky because the editor only displays Markdown files, making other files (like images) invisible. Initially, I didn’t even know where uploaded images went.

However, once you understand the logic, it’s straightforward:

1. While writing a blog post, copy the path of the md file.
2. When uploading images for an article, upload them to the same directory.
3. After uploading, the image path in the editor will include the full directory (e.g., ![Description](/content/editor/2025-05-08-sync-hugo-by-stackedit/j8iIBbPM2YN4gs54.webp)). Manually remove the path prefix, leaving only the filename (e.g., ![Description](j8iIBbPM2YN4gs54.webp)).