Convert Medium Blogs to Markdown
Introduction
“The best way to predict your future is to create it.” — Peter Drucker
Scratching my own itch and giving back to the community, that’s what I love about open source. If you write blogs on medium or simply want to convert someone’s else blog into Markdown, this article is for you.
Why convert blogs?
Running my own website means porting blogs from medium to the blogs section on the website.
While it seems easy at first, there are surprising little quirks and surprises in the whole process.
Blog -> Markdown; Existing Solutions
I’ve tried a few solutions that worked to some extent, but each had its drawbacks:
- Markdownload — Firefox Extension
➕ Quick and easy copy parts of a webpage as Markdown
➕ Ability to download a whole page, including images
➖ Medium blogs are way too messy and require manual cleanup
➖ Image references are not updated in the markdown and still point to original URLs
2. Mediumexporter
➕ Easy to use
➕ Works as expected
➖ Not maintained
➖ Stopped working for me
Requirements
As any self-respecting software engineer, I’ve started from gathering requirements \s. Here is what I needed:
- Download blog and images into
_media
folder and updates the Markdown file with local image paths. - Use
pandoc
to convert the blog into Markdown - Clean up the Markdown file by removing
div
,span
tags and other formatting issues. - Removes content that is added automatically by medium before and after the blog, aka capture the
<article>
tag - Removes unnecessary empty lines.
Let’s try it out
The CLI is distributed as Node.js app and can be installed with:
npm install -g medium-blog-exporter
which gives us a mediummd
binary.
💡naming could have been better here, but lots of good names were already taken by folks trying similar ideas.
Grabbing one of my recent blogs and converting is as easy as:
mediummd 'https://medium.com/itnext/why-is-building-pipelines-different-from-software-development-13ebd479edc4'
This should convert the article to Markdown, create a new folder called _media
and download images from the blog as well as reference them in the blog.md
file.
Updated HTML written to /home/decoder/dev/test/blog.html
HTML successfully converted to Markdown.
Markdown file cleaned successfully!
Temporary HTML file deleted successfully!

Closing Thoughts
The code is far from perfect and there are a few things on the todo list:
- Add unit/integration tests.
- Add YouTube
iframe
conversion. - Only download images that are needed (currently, all images are downloaded).
- Optionally output Markdown under a different name.
- Optionally add front matter headers.
Creating this tool has been a fun project, and I hope it helps others streamline their blog conversion process. If you have any suggestions or improvements, feel free to contribute to the project.
Thanks for taking the time to read this post. I hope you found it interesting and informative.
🔗 Connect with me on LinkedIn
🌐 Visit my Website
📺 Subscribe to my YouTube Channel