Migrating from Jekyll to Micro.blog

I recently returned to Micro.blog for the third time (and my old username was even still available). I decided that this time, I would take full advantage of Micro.blog and migrate my Jekyll blog over to Micro.blog. I like that my blog is just static HTML and image files, but it’s kind of inconvenient to actually write. I have to be at my Mac because I need Ruby. I can’t take a photo with my phone and post it without some effort. Micro.blog is just easier, and should the need arise, I can export my site as Markdown files and move back to Jekyll.

There’s not a lot of information on the web about converting a Jekyll site to plain Liquid-free Markdown files. Fortunately, I found this blog post that pointed me to Pandoc.

This is how I migrated my Jekyll site to Micro.blog. If you want to do it the same way, I put the scripts you’ll need in this GitHub repository. The instructions assume some familiarity with the terminal and Python.


  1. Clone the repository or download the individual files.
  2. Install Python 3.
  3. Install Pandoc.
  4. Open your terminal app.
  5. pip install pypandoc
  6. pip install requests (optional; if you want to check the converted Markdown files for bad links)

Generate a JSON feed of your Jekyll site

  1. Copy feed-all.json to the root of your Jekyll site.
  2. Build your site.

Set variables in json-to-md.py

  1. In the line json_file = '/<Jekyll root>/_site/feed-all.json', change <Jekyll root> to the root of your Jekyll directory.
  2. In the line output_dir = '/<Jekyll root>/_ToMicroBlog', change <Jekyll root> to the root of your Jekyll directory.
  3. In the line static_asset_paths = ['/images/'], add paths to your static assets (e.g., images). Make sure you include leading and trailing slashes. Separate multiple paths with commas, e.g., ['/images/', '/assets/']

Convert JSON to Markdown

  1. cd to the directory that contains json-to-md.py.
  2. Type ./json-to-md.py and press Enter.

Clean up the Markdown files

All files will be output in /<Jekyll root>/_ToMicroBlog.

Review posts-with-img.txt, posts-with-code.txt and posts-with-youtube.txt. Clean up anything that didn’t convert cleanly.

<img> tags

Micro.blog will only import the image file listed in the src attribute of <img> tags. If you have srcset in any <img> tags, you’ll need to remove those from your Markdown files (or manually upload the image files and fix the URLs after importing to Micro.blog). The posts-with-img.txt file will list all Markdown files that contain <img> tags so that you can find them more easily.

Code blocks

If you have code blocks with line numbers in your Jekyll posts, they won’t convert cleanly to Markdown. Even without line numbers, code blocks may not convert with the proper line breaks, spacing and indentation. The posts-with-code.txt will list all files that have code blocks.

YouTube embeds

For YouTube embeds, posts-with-youtube.txt will list the YouTube IDs in each post. Add {{< youtube ID >}} to the Markdown file (replace “ID” with the ID in the file). This is Hugo shortcode for a YouTube embed. Micro.blog will translate this to the embedded video.

Check for bad links (optional)

check-links.py can check for bad links in your converted Markdown files. If you want to check the links, make sure you installed Requests in Setup step 5. Then type ./check-links.py and press Enter. The script will produce a file called bad-links.txt that lists the bad links in each Markdown file. A link is considered “bad” if it doesn’t return HTTP 200 (OK).

Import to Micro.blog

Zip your Markdown files and import the zip file to Micro.blog.

Rebuild the site (maybe)

After importing the Markdown files, all of my imported posts were listed in my account under Posts, but only a few showed up on my blog. I had to rebuild the site by clicking the Rebuild button at the top of this page.

Check for bad links (again)

I used Integrity to check the site for bad links after everything was imported. This helped me find some srcset attributes that I hadn’t cleaned up. To easily find the posts that contained bad links, I downloaded the Micro.blog site as Markdown so that I could just search the directory in Visual Studio Code. Then I manually fixed the posts in the Micro.blog Mac app.

Don’t mark your posts as drafts

I thought I could import all of my posts as drafts (by setting draft: true in the front matter of the Markdown files), clean up formatting issues, and then publish. Don’t do this; you’ll lose your original publish dates. I made this mistake and ended up deleting and reimporting all of my posts.