medium-2-md: Convert Medium posts to markdown with front matter

A CLI tool that converts exported Medium posts (HTML) to Jekyll/Hugo compatible markdown with front matter

medium-2-md is a simple CLI tool which takes a directory containing Medium posts’ HTML files (or a single post URL) and converts them into markdown. Not only that, but it also adds a rich front matter to these converted markdown files so that they can be directly used in Jekyll or Hugo.

The CLI tool is written with node.js. It expects the input HTML files to have the same tags and attributes as the files contained in the posts directory shown in the picture above. That way it is able to extract all the information needed for the front matter.

It has not been tested for general purpose HTML to markdown conversion; it is only suitable for HTML files exported from Medium stories/posts.

Usage

medium-2-md is available as an npm package so that it can be easily downloaded and used without the need of going through the code. All you need to do is download and install it (globally) and then use it directly from the command line. Follow the steps listed below to use medium-2-md.

Step 1: Export and extract your Medium posts from your Medium account.

• Go to https://medium.com/me/settings and scroll to Download your information. Click the download button. This will give you a medium-export.zip archive containing all your Medium content.
• Extract the .zip archive downloaded in the previous step. It will have a sub-directory called posts.
• Copy the path of this posts directory.

Step 2: Install node.js and medium-2-md on your system.

• Download and Install node.js — [https://nodejs.org/en/download/](https://nodejs.org/en/download/.).
• Install medium-2-md package — npm i -g medium-2-md.

Note: The -g flag means that you are installing the package globally. It is essential in order to use the package directly from the command prompt/terminal.

Step 3: Run the following command to convert all your Medium posts (HTML) to markdown files.

medium-2-md convertLocal '<path of the posts directory>' -df

That’s it. The output markdown files will be stored in a sub-directory called md_<a big number> in the posts directory itself. (By the way, that big number is coming from the Date.now() JavaScript function, added to differentiate the output folders in case we go crazy with it.)

Convert from post URL

The CLI tool can also be used to convert a single Medium post from it’s url. It requires an additional parameter -o for output directory where the converted markdown file can be written. To convert a Medium post to markdown from it’s url, run the following command after installing the npm package,

medium-2-md convertUrl '<url of the Medium post>' -o '<path of output directory>' -f

The converted markdown files will also have front matter which will have the title, description, published date and canonical URL of the original Medium post/story.

More details about the package are available in the readme file at the medium-2-md GitHub repository.

This tool helped save a lot of time when I was converting all my stories/posts to markdown. I tested the converted markdown in a test Hugo site and it worked like a charm.

A couple of things that we need to take care manually are code fences and tags. There is no tag related information in the exported Medium files. The code fences are also exported as plain text and the markdown conversion ignores them too.

Give it a try and feel free to provide your feedback using the issue tracker on the GitHub repository — https://github.com/gautamdhameja/medium-2-md.

Originally published at www.gautamdhameja.com on December 30, 2018.