Skip to main content
Join the official 2019 Python Developers SurveyStart the survey!

Generates ('tangles') source code from Markdown documents

Project description

app-badge Version License Format PyVer Downloads

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.

Project details


Download files

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

Files for md-tangle, version 1.3.0
Filename, size File type Python version Upload date Hashes
Filename, size md_tangle-1.3.0-py2-none-any.whl (6.4 kB) File type Wheel Python version py2 Upload date Hashes View hashes
Filename, size md_tangle-1.3.0-py3-none-any.whl (6.4 kB) File type Wheel Python version py3 Upload date Hashes View hashes

Supported by

Elastic Elastic Search Pingdom Pingdom Monitoring Google Google BigQuery Sentry Sentry Error logging AWS AWS Cloud computing DataDog DataDog Monitoring Fastly Fastly CDN SignalFx SignalFx Supporter DigiCert DigiCert EV certificate StatusPage StatusPage Status page