Convert reStructuredText to Markdown

This guide demonstrates how to convert reStructuredText (reST) files to Markdown, optionally including front-matter metadata in a Pelican context.

Tools Used in this Guide

The following tools (tap on them for the links) were used in this guide:

• pandoc: To convert from reST to Markdown
• fd: To recursively find files on which to execute commands
• sd: To recursively find and replace text strings
• trash | macos-trash (optional): To safely, non-destructively remove files
• Pelican (optional): To test converted Markdown files via Pelican
• Related resource, just for reference: rst_to_md.sh

Convert reST Files to Markdown

Use pelican-quickstart to create a new project called testsite and copy the Pelican web site’s reST content into the new project:

cd ~/Desktop/
pelican quickstart
cd ~/Desktop/testsite
cp -r ~/projects/pelican-website/content/news/ content
cd ~/Desktop/testsite/content

Recursively find and convert all .rst files to Markdown:

fd -e rst --exec pandoc {} -f rst -t markdown -o {.}.md

Trash the .rst files (replace trash with rm if trash is unavailable, or with git rm if in a Git repository):

fd -e rst --exec trash

Try converting the first # […] header to a title: […] metadata field in a single file:

sd -n 1 '^# (.*)$' 'title: $1' pelican-4.10.md

Try cleaning up the misshapen remaining metadata headers in a single file:

sd '\n(.*)\n\n:   (.*)\n' '$1: $2\n' pelican-4.10.md

Inspect the modified file. Assuming the above has done everything necessary, it is time to perform those operations recursively on all Markdown files.

Recursively convert the first # […] header to title: […] metadata:

fd -e md --exec sd -n 1 '^# (.*)$' 'title: $1'

Recursively clean up the misshapen remaining metadata headers:

fd -e md --exec sd '\n(.*)\n\n:   (.*)\n' '$1: $2\n'

Use Pelican to test building the converted Markdown files:

cd ~/Desktop/testsite
pelican build

→ Done: Processed 23 articles, 0 drafts, 0 hidden articles, 0 pages, 0 hidden pages and 0 draft pages in 0.29 seconds.

In this case, the conversion was successful ✨

Did this work for you? Reach out and let me know!