Skip to main content

Image Hosting Migration: From Yuque to GitHub, Hand-Held Tutorial

Continued from: 🚀 No course-selling! 10 minutes to launch a site that collects inquiries

In content creation and migration, we often hit a thorny problem: content exported from Yuque, Notion, and other note-taking platforms has image links protected by "hotlink protection". The moment you publish that content on your own site or blog, the images all break — you get the ugly "broken image" icon.

This article gives you the ultimate fix: use the powerful Markdown editor Story-Writer, paired with free and reliable GitHub as your image host, to bulk-migrate those protected image links in one click. The tutorial covers software installation, image host configuration, and live conversion — with detailed walkthroughs and screenshots for every pit beginners commonly hit. Follow along step by step and you'll get there.

1. Preparation: Download & Install​

First, download and install Story-Writer. Pick the version for your OS.

Download links:

【Special note for macOS M-series chip users】 If you're on an ARM Mac (M1/M2/M3), download the osxarm version. If it won't launch, open Terminal and run:

# Assuming you put the extracted folder in Downloads
cd /Users/your-username/Downloads/Story-writer-osxarm
xattr -cr ./Story-writter.app

This command removes the macOS quarantine attribute and lets the app run. The rest of the install is the same as any other app — skipping the details.

2. Basic Setup: Optimize Your Editing Experience​

To make it easier to observe Markdown source and preview side-by-side, we recommend disabling Story-Writer's default WYSIWYG mode.

  1. Open Story-Writer. In the status bar at the bottom of the editor, find and click "Modify editor config".

    Click Modify editor config

  2. In the config popup, uncheck "WYSIWYG".

    Uncheck WYSIWYG

Now your editor shows Markdown source on the left and live preview on the right — the classic layout. This helps a lot when checking whether image links got correctly replaced.

3. Core Configuration: Binding the GitHub Image Host​

This is the most critical — and most error-prone — step in the whole flow. We'll set up GitHub step by step, then bind it into Story-Writer.

Step 1: Open the Story-Writer Binding Settings​

  1. Click the gear icon in the bottom left of Story-Writer to open Settings.

    Open Story-Writer Settings

  2. In the settings menu, go to "Storage" → "Bind".

    Go to Bind settings page

  3. In the image hosts list, find and click githubimg to configure.

    Choose githubimg service for configuration

Step 2: Get a GitHub Access Token​

The Token is like a password for Story-Writer to access your GitHub repo — keep it safe.

  1. On the githubimg config screen, click the link next to token — it takes you to GitHub's Token generation page.

    Click the link to generate a Token

  2. Log into your GitHub account (Google sign-in supported).

    Log into GitHub account

  3. On the "New personal access token" page, configure as follows:

    • Note: name this Token for easy identification, e.g. storywriter-token.
    • Expiration: set validity. Recommended "No expiration" or a long duration.
    • Select scopes: most important step! You must check repo, which automatically includes all sub-permissions.

    Set Token name, expiration, and permissions

  4. Scroll to the bottom, click "Generate token".

    Click Generate token button

  5. Copy and save the generated Token immediately! It's shown only once — once you leave the page, you can't see it again.

    Copy and save the generated Token

Step 3: Create and Initialize a GitHub Repo​

This repo will be your online image storage.

  1. On GitHub, click the "+" in the top right, choose "New repository", or go directly to github.com/new.

    Create a new GitHub repo

  2. Set the repo info:

    • Repository name: name the repo, e.g. nibaba.
    • Public/Private: must select Public, otherwise the images can't be accessed externally.
    • Click "Create repository".

    Fill repo name and set to Public

  3. Repo created successfully.

    Repo created successfully

  4. 【Critical pit-avoidance】Initialize the repo. A newly created empty repo can't be used directly — Story-Writer will error. We must create a file in it to initialize. The simplest way is to create a README.md.

    • Click "creating a new file" or "Add a README file" on the page.

    Click create README to initialize the repo

    • The filename defaults to README.md — no need to change. Click "Commit changes..." top right, then click "Commit changes" again in the popup.

    Commit the README creation

  5. Initialization complete. Note: the repo's default branch is now main.

    Init complete — note default branch is main

Step 4: Finish Configuration in Story-Writer​

Now back to Story-Writer's githubimg config screen, fill in the info you've prepared.

Fill GitHub image host config in Story-Writer

  • token: paste the Token you just generated on GitHub (usually starts with ghp_).
  • Repo: fill in your repo name, e.g. nibaba.
  • Filename generation rule: recommend /img/{{filename}} — all images will go into the img directory in the repo, easier to manage. Avoid Chinese paths.
  • 【Critical pit-avoidance】Corresponding branch: change the default master to main, matching the branch name you see on GitHub.

Step 5: Common Issues & Fixes​

If you hit errors during config or testing, 99% of the time it's one of these two causes:

  • Error 1: Repo not initialized (409 Conflict Error) If you skipped repo initialization, you'll see a 409 error during testing:

    {"path":"/repos/apan-tony/nibaba/git/refs/heads","request":{"dataType":"json"},"error":409}

    409 error from uninitialized repo Fix: go back to GitHub, follow Step 3 to create a README.md in the repo.

  • Error 2: Branch name mismatch If your branch is main but you filled master in Story-Writer, you'll see this error: Error from branch name mismatch Fix: in Story-Writer's githubimg config, change "Corresponding branch" from master to main.

Step 6: Activate & Test the Image Host​

  1. Once config is clean, go back to "Bind" page, check githubimg to make it the current default image host.

    Check githubimg as default image host

  2. Close settings and return to the main editor view.

    Click return to editor view

  3. Test paste-upload: take any screenshot, then in Story-Writer's editor press Ctrl+V (or Cmd+V) to paste. If the image link auto-converts to a raw.githubusercontent.com URL — congrats, image hosting is configured!

    Paste a screenshot to test image hosting

4. The Real Deal: One-Click Bulk Migration​

Everything's ready — let's execute the final conversion.

Step 1: Find the "Image Host Transfer" Feature​

  1. First, paste the full Markdown you copied from Yuque (or wherever) — the one with the old image links — into Story-Writer's editor.

  2. In the editor's top menu bar, find and click "Image Host Transfer".

    Find and click Image Host Transfer button

    【Tip】 If you don't see this menu bar, you may be in "tab mode". Click "Toggle tab mode" in the top left.

    Click Toggle tab mode to show menu bar

    Once toggled, you should see the "Image Host Transfer" button on the right.

    Image Host Transfer button in the other mode

Step 2: Execute the Conversion​

We'll use this snippet with Yuque image links (cdn.nlark.com) as an example:

![](https://cos.files.maozhishi.com/data/web/web-files/img/1753201459682-632743aa-d982-4443-a0d9-de48452e33c3.png)
<font style="color:#FF0000;">Product code HY-001</font>
![](https://cos.files.maozhishi.com/data/web/web-files/img/1753201460043-e8373b48-adbc-4c52-ad29-f1f3835d5dae.png)<font style="color:#FF0000;">Product name: Rectangular glass food container (2 compartments) (1040ML)</font>
<font style="color:#FF0000;">Capacity: 1040ML</font>
![](https://cos.files.maozhishi.com/data/web/web-files/img/1753201460403-cdc4a3bf-925a-4d33-a61a-d17e5f569df9.png)
<font style="color:#FF0000;">Product code HY-003</font>
<font style="color:#FF0000;">Product code HY-004</font>
![](https://cos.files.maozhishi.com/data/web/web-files/img/1753201460699-9fc9706a-dcf9-40cd-a381-1f88dab442e8.png)<font style="color:#FF0000;">Product name: Round glass food container (2 compartments) (960ML)</font>
<font style="color:#FF0000;">Capacity: 960ML</font>

  1. Paste this into Story-Writer, click "Image Host Transfer".

    Click Image Host Transfer after pasting content

  2. In the "Network Image Address Conversion" popup, check "Select all" in the top right, then click "Convert" at the bottom. The "Converted address" column is empty for now.

    Select all and click Convert in the conversion popup

  3. Wait patiently. Story-Writer will start downloading the original images and uploading them to your GitHub repo — the popup shows "Processing...". Don't do anything during this process.

    Conversion in progress

Step 3: Verify the Results​

  1. Once conversion completes, the "Converted address" column fills in with new GitHub URLs. Click "Confirm".

    Conversion complete — new URLs generated

  2. Back in the editor, you'll see every image link in the body has been successfully replaced!

    Image links in body successfully replaced

The converted content looks like this — image links now point to stable, hotlink-free GitHub URLs:

![](https://raw.githubusercontent.com/apan-tony/nibaba/main/img/1753361533417.png)
<font style="color:#FF0000;">Product code HY-001</font>
![](https://raw.githubusercontent.com/apan-tony/nibaba/main/img/1753361533419.png)<font style="color:#FF0000;">Product name: Rectangular glass food container (2 compartments) (1040ML)</font>
<font style="color:#FF0000;">Capacity: 1040ML</font>
![](https://raw.githubusercontent.com/apan-tony/nibaba/main/img/1753361533421.png)
<font style="color:#FF0000;">Product code HY-003</font>
<font style="color:#FF0000;">Product code HY-004</font>
![](https://raw.githubusercontent.com/apan-tony/nibaba/main/img/1753361533420.png)<font style="color:#FF0000;">Product name: Round glass food container (2 compartments) (960ML)</font>
<font style="color:#FF0000;">Capacity: 960ML</font>

That's it — you've migrated every image to your own image host. This polished Markdown "raw material" is now safe to hand to AI for further polishing, or to publish directly to your site and blog.