md-tangle 1.0.0

Generates ('tangles') source code from Markdown documents

md-tangle

This project is a result of wanting config and setup files to be part of a document explaining my setup. I originally used Org-mode and org-babel-tangle in Emacs to achieve this. I really like Org-mode and Emacs, but I'm not fond of being dependent on one editor. This is the reason I wanted a CLI, and a more widely used document markup language.

This way of programming is called literate programming. This programming paradigm was introduced by Donald Knuth. The idea is to write a program as an explanation of the program logic in a natural language interspersed with snippets of traditional source code. The source code can then be generated ("tangled") by using some tool.

As Markdown is used by most programmers, I saw that language fit for the task. Markdown is a plaintext-ish format popular with programmers. It's simple, easy and already has support for embedding code blocks using ``` or ~~~~, mostly for the purposes of syntax highlighting in documentation.

Add some kind of header to all tangled files ??

Command

By adding the command tangle:<path/filename>, this tool will tangle tagged code blocks to given file. Supports ~ for home directory.

If the file already exists, the user will be prompted with the option to overwrite, unless the -f/--force flag is added.

Flags

• -h/--help: Show help message and exit
• -f/--force: Force overwrite of files if the already exists
• -v/--verbose: Show output

Usage

Take the following example:

HelloWorld.md

# Some title

Describing the following code... bla bla.

~~~~javascript tangle:helloWorld.js
console.log("Hello, world");
~~~~

By adding some css ... 

~~~~css tangle:styles/button.css
#button1 {
    border: none;
}
~~~~

By adding installing md-tangle with pip, one could simply produce files from this file by executing:

$ md-tangle -v HelloWorld.md 
helloWorld.js                                      2 lines
styles/button.css                                  4 lines
$ ls 
helloWorld.js HelloWorld.md styles

If one wishes to use Python 2, one could easily install md-tangle2 instead.

Documentation

The documentation for md-tangle is of course written in Markdown, and tangles to the source code.