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.
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
.
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.
-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=',')
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
The documentation for md-tangle
is of course written in Markdown, and tangles to the source
code.