Easy blog migration from Medium to your own site using Python

Recently I migrated my existing articles from Medium to my own new website (https://jerrychi.com) in a quick, low-code way. I wanted to have both blog articles and permanent pages (e.g. “About Me” page) and high customizability while spending minimal effort and money.

snapshot of jerrychi.com

You can do this too! Here’s how:

Register a domain name. I used https://domains.google/ to register jerrychi.com, paying about $12 per year. This is the only thing I’m paying for.

Install required Python libraries including Pelican (the Python-based static site generator for creating personal blogs/websites) on your local laptop. E.g. pip install -r requirements.txt (see my requirements.txt). I used Python 3.8.6 in a conda environment but other setups should work too.

Pelican logo

Auto-convert any Medium articles you choose to Markdown files (which are compatible with Pelican, which will then auto-convert them to HTML/Javascript) using the medium_to_markdown tool described at https://willkoehrsen.github.io/writing/markdown/converting-medium-posts-to-markdown-for-your-blog / . I did slightly tweak his code to e.g. filter out a few specific words. This doesn’t require any special access to your Medium account; it’s just scraping the text from the public internet.

Push your code to a new Github repo.

• You can host the website on Github Pages for free, up to 1 GB of storage (nothing beyond that even if you want to pay). If I ever need more than 1 GB, I might migrate to Heroku.
• You can use your own custom domain (in my case jerrychi.com)

We need a master or main git branch for all the code and then a gh-pages branch to store the actual website assets that are served when people visit your site. Thankfully one can just use a tool called ghp-import to automate pushing the only the needed to gh-pages branch. You can see how I use this tool. After pushing to github, usually changes are reflected in a few seconds on my website.

• Tip: style changes to CSS files etc. may require an “empty cache and hard reload” in Chrome to be visually reflected on the website due to caching.

Pelican also supports add-ons, themes, etc.

• See the pelican-themes repo for instructions on themes.
• I chose to use the Flex theme which includes many nifty features such a mobile-first responsive UI. I cloned this Flex repo directly rather than cloning from the pelican-themes repo which pins Flex at an older version.
• I also edited the pelican-templates/Flex/static/stylesheet/style.less file to customize the font style (my first time dealing with the Less language but it was easy to edit).

That’s it! Now you have a nice shiny new personal website~

So, why did I choose Pelican? I also considered Nikola and Django:

• Nikola: the second-most popular Python static site generator after Pelican. I did initially try building with Nikola but got frustrated with the documentation being a bit unclearly worded and the lack of resources/answers when e.g. googling around for an issue. Pelican is more established and popular with more discussion/answers for potential issues.
• Django: the most popular Python web backend framework. I did take the Django official tutorial, which was enjoyable and extremely well-written. However, Django is much more complicated than Pelican (which is natural since Django is a general-purpose framework for creating any sort of webpage) and I’d likely end up combining Django with a frontend framework like React (meaning one more framework to learn). The complexity and work required was overkill for needs: a simple personal website. I’ll come back to learn Django+React if I need a much fancier site.

UPDATE 2022–10–18: it seems the above method no longer properly converts the image links to Markdown format. My preferred way around this is just manually editing the Markdown files after conversion to add back the images (takes me about 20 seconds). Another way is to use something like https://github.com/gautamdhameja/medium-2-md but that adds the hassle of manually exporting all your data from the Medium settings page each time you want to convert a new article.