codedown
v3.2.1
Published
Extract and run code blocks from Markdown files
Downloads
1,030
Maintainers
Readme
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)
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