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.

Installing

This CLI tool can easily be utilized by adding md-tangle to your PATH, or by installing the package with pip.

See the package on pypi.org, or just install with pip install md-tangle.

Command

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

One can tangle the code block to multiple files by separating the files with chosen separator (default: ,).

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
• --version: Show installed version
• -f/--force: Force overwrite of files if the already exists
• -v/--verbose: Show output
• -d/--destination: Overwrite output destination
• -s/--separator: Separator for tangle destinations (default=',')

Usage

Take the following example:

HelloWorld.md

# Some title
Describing the following code... bla bla.

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

## Styling
Adding header for my css files:

~~~~css tangle:styles/button.css,styles/input.css
/* Styling for mye awesome app */
~~~~

By adding some css ... 

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

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

By 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
styles/input.css                                   4 lines
$ ls 
helloWorld.js HelloWorld.md styles

Documentation

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