Skip to main content

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.

Source Distributions

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

Built Distribution

md_tangle-1.4.4-py3-none-any.whl (6.5 kB view details)

Uploaded Python 3

File details

Details for the file md_tangle-1.4.4-py3-none-any.whl.

File metadata

  • Download URL: md_tangle-1.4.4-py3-none-any.whl
  • Upload date:
  • Size: 6.5 kB
  • Tags: Python 3
  • Uploaded using Trusted Publishing? No
  • Uploaded via: twine/6.1.0 CPython/3.12.3

File hashes

Hashes for md_tangle-1.4.4-py3-none-any.whl
Algorithm Hash digest
SHA256 1480065c779b1c3971b0b8dfb7f7a33c54e7f02ae19b65caaf0ad2e7a6d82d46
MD5 62ea637bb866a1f81ad358a4266fdc27
BLAKE2b-256 29a491c20be99dffa2938f8512b2c1e72dd9b44bf3dabf0783beeef4965fe430

See more details on using hashes here.

Supported by

AWS Cloud computing and Security Sponsor Datadog Monitoring Fastly CDN Google Download Analytics Pingdom Monitoring Sentry Error logging StatusPage Status page