PS: I added the warning above manually. It's now June 16, 2026, and Shiroi has been switched to yohaku, so this article isn't very relevant anymore.

I ran into a few problems migrating from Gridea to Shiroi. Here's what I ran into — and how I worked around them.

1. Kotlin Code Blocks Can Crash Rendering in Shiro

When Shiro renders blog posts, pages can crash if a Kotlin code block appears in the article. Shiroi doesn't have this issue.

After removing the Kotlin code block, the page rendered normally. I then switched directly to Shiroi.

I haven't been able to reliably reproduce this, and the root cause might not even be the Kotlin code block itself. The code block that triggered the issue was:

testImplementation 'org.junit.jupiter:junit-jupiter:5.12.2'

2. You Can Add More Social IDs via Requests

3. Adding More Social IDs via API

The request endpoint is:

API address + /master

For example:

https://www.ruqiu.life/api/v2/master

The request method is:

PATCH

Example request body:

{
  "socialIds": {
    "bilibili": "",
    "github": "",
    "netease": "",
    "steam": "",
    "email": ""
  }
}

The admin panel itself sends this request when saving social ID information. You can copy the request headers from the developer tools and then send the request yourself.

Additionally, Shiro / Shiroi supports some other social IDs, such as:

1. Twitter / X
2. Telegram
3. RSS

I don't yet know the exact field names for these in the request body.

Watch out: Don't leak your authentication info when copying request headers.

3. Images Not Uploaded via MX Space May Crash Article Rendering

Images that weren't uploaded through MX Space itself can cause articles to crash during rendering in Shiro / Shiroi.

Specifically:

When writing an article in the MX Space admin panel, the preview looks fine; When switching to Shiro / Shiroi to view the article, the page rendering crashes; Going back to the MX Space admin panel to update the article, after opening the article settings, you'll find that the HTML element for setting images doesn't display; At this point, the article also can't be updated normally and shows an error similar to:

images.0.nested property images must be either object or array

This still happens on the latest version.

A temporary workaround is: replace the first image inserted in the article with one uploaded through MX Space. This can temporarily prevent the rendering crash.

Also, notes don't have this problem.

4. The Frontend Doesn't Update Immediately After Updating the Theme Cloud Function

After updating the theme cloud function in the admin panel, the frontend doesn't update right away.

This is normal behavior. You need to wait for some time before Shiro / Shiroi syncs the update.

5. Both a Network Error and a Success Message Appear When Updating Cloud Functions

Sometimes when updating cloud functions, both a "network error" and an "update successful" message appear simultaneously.

The reason is unknown, but it doesn't seem to have any impact—the actual result is still a successful update.

6. AI Summary Generation Requires JSON Schema Support

The AI service configured for the AI summary generation feature must support JSON Schema.

If it doesn't, you might see:

invalid json

And the backend will return a 500 status code.

7. AI Summaries May Be Generated Repeatedly After Publishing

Sometimes after publishing an article, the AI automatically generates a summary.

But after clicking into the article, it generates the summary again. The cause of this issue is unknown.

8. Algolia Search's Write Key

For Algolia Search, the write key is now the admin key mentioned in the official documentation.

Just fill in the admin key in the key field of the Algolia Search settings.

9. Outlook Email Cannot Send Mail Using Email and Password

Outlook no longer supports sending mail with just an email and password, and app passwords don't work either.

For now, Google email still works normally.