Migrating Articles from Gatsby to Zenn: Getting Started and Common Pitfalls

For about the past two years, I've been putting detailed articles on my own Gatsby-based blog or on Notion, and recently I've started migrating them bit by bit to Zenn (it’s becoming more manual than expected, and some articles are past their prime, so I haven't decided how much I'll actually move yet).

In this article, I'll describe why I had this change of heart and the pitfalls I encountered.
I hope this helps anyone considering something similar.

Migration Pitfalls

First, as the main topic, I will list the pitfalls I encountered when migrating.
Please refer to this if you are planning something similar.

Regarding Builds

• Build limit is 50 files per day
  • If you try to import a large number of articles automatically, you might get stuck.
• Build limit is 30 times per day
  • In my case, I was constantly updating my article creation tools and hit the limit quickly, so it's better to use branches properly.
  • There is a preview function in zenn-cli, so it's good to utilize that.
  • I couldn't find whether the "day" is defined as starting at 0:00 or 24 hours from the last push.
  • I thought not being able to push updates for 24 hours would be scary if there were a critical mistake, so it might be nice if it recovered in a shorter span? Or if the remaining count was visible?
    • Update 2020/09/24: Since it’s now possible to edit articles from the Web even for those uploaded via GitHub integration, you can probably edit there in an emergency.

Regarding Article Metadata Validation

There are several cases where you might run into validation errors during article migration. You can generally check the validation rules in the following file:
https://github.com/zenn-dev/zenn-editor/blob/master/packages/zenn-cli/utils/validator.ts

• Title length is currently limited to 60 characters. It sounds like a lot, but if it includes English characters, you can hit the limit quite easily, so you need to trim it well.
  • This might not be limited to Gatsby.
• Slug must be 12 to 50 characters.
  • In my case, I put the date at the beginning, so I didn't have much trouble with the lower limit, but occasionally it would exceed 50 characters.
• Tags cannot include symbols or spaces.

Regarding Gatsby

• Redirecting from Gatsby is a bit tricky.
  • After considering various options, I found that setting up redirect rules in vercel.json / now.json seemed the easiest.
    • Something like this
    • It's better to account for the trailing slash in the src like /blog/my-slug/?.
  • I tried things like gatsby-plugin-client-side-redirect but couldn't get it to work well...
• Since HTML cannot be used, it needs to be replaced.
  • It's easy to miss things like <!-- HTML comments becoming visible.

Why did I migrate in the first place?

The main reasons are as follows:

• Maintaining my own blog became a burden
• The GitHub integration feature makes migration costs and risks low
• There are advantages to hosting on Zenn
• It was a long holiday

Tired of the DIY blog / Enthusiasm dropped

I’ve been running my own blog for about two years, but I’ve reached the point where it's time for a major overhaul. It feels like moving to a new rental apartment (actually, I’m impressed I lasted two years).

Of course, there are benefits like high customizability and learning things you don't experience at work, but in the end, I found myself constantly fighting small errors after updating dependencies or spending all my time tweaking things I didn't like instead of writing articles. I realized once again that this isn't really for me.

Originally, my stance towards technical articles was largely as a public memorandum—things like "I'll write this down so I don't forget the handy technique I tweeted about" or "There are probably one or two other people in the world troubled by the same thing." With that level of intensity, it was hard to maintain enthusiasm and avoid burnout.

Migration costs and risks are low thanks to the GitHub integration feature

The reason I stuck with a DIY blog despite the effort was that I wanted to avoid the risk of depending entirely on another service (basically, the problem of what happens if the service shuts down or I want to leave).

I knew that DIY blogs had high costs, and I tried new services whenever they appeared, but I had developed a mindset where I couldn't accept "hosting on another service = completely entrusting my articles to that site."

This is where Zenn's GitHub integration feature is a huge deal (though it's currently in beta).
If this didn't exist, I probably would have thought, "I'll wait and see for another month."

As the name suggests, this feature reflects articles on the site when you place Markdown files following a specific format in your GitHub data.

While there are differences in the details, such as how deletions are managed or the fact that slugs cannot be changed, the experience is almost the same as what I was doing with Gatsby.

With this, even if the service ends, I can just make the GitHub repo public to keep the articles available, and I can optimistically believe that returning to a DIY blog wouldn't be that difficult.

Also, it's not a cross-posting or copy-paste feature; when you edit, the updates are reflected. For example, you can grep and replace across multiple articles written about specific elements.
Since it also supports a frontmatter format like dev.to, you can even use it for notes by including your own metadata.

However, the following points might require some consideration:

• Some Zenn-specific notations are available (like warning messages, which are very convenient). Should I use them?
  • zenn-markdown-html is public, so it seems possible to reproduce them, but since the license for zenn-markdown-html itself isn't explicitly stated, it might not be possible to use it as is.
  • The ::: details special notation used in this block is extremely useful...
• What about images?
  • Images are always a bit of a hassle. I feel like hosting them myself might be an option.
• I had some demos on StackBlitz, so migrating those might be a bit tough.

There are benefits to being on Zenn

While I've listed some somewhat passive reasons so far, there are obviously great advantages to being on a public service.

In terms of SEO, it's clearly more beneficial than doing it individually, and the response to articles increases.
While I understand the issues with using "Like" counts as a metric, it's honestly nicer to have some reaction. Without this, it's hard to find the motivation to overcome the barrier between "I'll just post this as a one-liner on Twitter" and "I should summarize this properly."

Needless to say, I have high expectations for the beautiful UI, tipping (support), and publication features. A platformer that addresses the financial aspect is very welcome and serves as great motivation.

Since I still feel the hurdle is a bit high, I can't use the Books feature casually yet, but I'd like to try it out eventually.