Skip to main content

Generates ('tangles') source code from Markdown documents

Project description

app-badge Version License Format PyVer Downloads


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, 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:

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

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

## 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.js                                      2 lines
styles/button.css                                  4 lines
styles/input.css                                   4 lines
$ ls 
helloWorld.js styles


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

Project details

Download files

Download the file for your platform. If you're not sure which to choose, learn more about installing packages.

Source Distributions

No source distribution files available for this release. See tutorial on generating distribution archives.

Built Distributions

md_tangle-1.3.1-py3-none-any.whl (6.4 kB view hashes)

Uploaded py3

md_tangle-1.3.1-py2-none-any.whl (6.4 kB view hashes)

Uploaded py2

Supported by

AWS AWS Cloud computing Datadog Datadog Monitoring Fastly Fastly CDN Google Google Object Storage and Download Analytics Microsoft Microsoft PSF Sponsor Pingdom Pingdom Monitoring Sentry Sentry Error logging StatusPage StatusPage Status page