↓Skip to main content
IT Blog IT Blog
  1. All Posts/

markdown.bash

Tools Shell

What is it?

markdown.bash is a Markdown interpreter using only traditional Unix tools. Specifically, it only uses Bash, Sed, Grep, and Cut (in one small instance).

Why did I write markdown.bash?

Good question. There already exist Markdown implementations in a variety of languages. Plus, the original Markdown was written in Perl which exists on virtually all Unix machines. So I didn’t write it for any practical reason. Really I just wanted to see how much of it I could re-engineer in a single Bash script using mostly Sed for the transformations.

How to use it?

You use it just like any other Unix program – by either passing files to it or piping input into it.

sh markdown.sh file1 file2 file3 > output.html
echo "# heading1nnparagraph" | sh markdown.sh
sh markdown.sh samples/test.md

What is missing / different?

By my own rough estimate, markdown.bash implements about 95% of the Markdown language. Still there are some areas where it doesn’t.

  • It doesn’t convert E-mail addresses to a mix of decimal and hex entity-encoding. I really did not know a good, canonical way to do this in Unix/Linux. Suggestions are welcome.
  • It processes Markdown inside block-level HTML. According to the original spec: Note that Markdown formatting syntax is not processed within block-level HTML tags. E.g., you can’t use Markdown-style emphasis inside an HTML block. markdown.bash does process Markdown syntax within block-level HTML. I couldn’t think of a good way to implement this exactly like the spec.
  • Due to the line-by-line processing nature of Sed, I recommend always putting hard breaks (nn) between block-level elements (lists, paragraphs, etc). markdown.bash does a lot less implicit processing of elements separated by only one break (n) than the Perl version does.

Kudos

Before starting this project I had only a cursory understanding of Sed. I’m still not an expert, but I do know a lot more now. A couple of web resources were especially helpful.

Known issues

This script only works with GNU sed. So if you have both BSD sed and GNU sed installed (often happens on OSX), you will need to alias GNU sed. If you get the following error running this script, you will need to apply this fix.

sed: illegal option -- r

The least intrusive way to apply this fix is to uncomment the following two lines at the top of markdown.sh.

shopt -s expand_aliases
alias sed=gsed


↑