Codedown

Codedown is a little utility to extract code blocks from Markdown files. Inspired by literate Haskell, Codedown can be used to:

• Validate the correctness of code embedded in Markdown
• Run code embedded in Markdown
• Ship code and Markdown together in harmony

Quicker start

To skip installing Codedown locally, try it online.

Quick start

Install Codedown:

$ npm install -g codedown

Run Codedown:

Usage: codedown <lang> [...]

Options:
--separator <separator line>
--section <section number>

Example:
cat README.md | codedown haskell --separator=----- --section 1.3

Codedown reads Markdown from stin, extracts the code blocks designated as language <lang>, and outputs them to stdout. The example above extracts the Haskell code from section 1.3 of this file, and outputs it with five dashes in between each block:

x :: Int
x = 42
-----
main :: IO ()
main = putStrLn $ show x

We can pipe the output of Codedown to a language interpreter:

$ cat README.md | codedown haskell | runhaskell
42

$ cat README.md | codedown javascript | node
42

$ cat README.md | codedown scala | xargs -0 scala -e
42

Examples

This readme is a Markdown file, so we can use Codedown to extract code from it.

Variables in different languages

In the following code blocks, let's set x to 42 in different languages:

Haskell:

x :: Int
x = 42

JavaScript:

var x = 42;

Scala:

val x = 42

Console output in different languages

Now let's print x it to stdout in different languages. This time, the code blocks are nested within an unordered list:

• Haskell:

  main :: IO ()
  main = putStrLn $ show x
  

• JavaScript:

  console.log(x);
  

• Scala:

  println(x)
  

Docker

Build and run a Docker image:

docker build -t codedown:dev .

Use it to extract haskell code blocks and save to output.hs:

cat README.md | docker run -i codedown:dev haskell > output.hs

Sections and subsections

The section above is 1.3, counting by headings. It has two subsections (1.3.1 and 1.3.2). We can specify a section number to extract the content from just that section:

$ cat README.md | codedown haskell --section 1.3
x :: Int
x = 42

main :: IO ()
main = putStrLn $ show x

$ cat README.md | codedown haskell --section 1.3.1
x :: Int
x = 42

$ cat README.md | codedown haskell --section 1.3.2
main :: IO ()
main = putStrLn $ show x

We can also specify a section by heading:

cat README.md | ./codedown.js haskell --section '### Variables in different languages'
x :: Int
x = 42

Wildcard matching

Codedown can use wildcards to match file paths, which are used by some markdown implementations:

lib/codedown.js:

var x = 42;

$ cat README.md | codedown '**/*.js'
var x = 42

Additionally, you can use a special * character in place of the language option to extract any/all code blocks agnostic of language:

$ cat README.md | codedown '*'

Separator

If there are multiple code blocks in the same file, we can specify a separator to insert in between them:

$ cat README.md | codedown haskell --separator=-----
x :: Int
x = 42
-----
main :: IO ()
main = putStrLn $ show x