Generates ('tangles') source code from Markdown documents
Project description
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.
Command
By adding the command tangle:<path/filename>
, this tool will tangle tagged code
blocks to given file. Supports ~
for home directory.
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-f
/--force
: Force overwrite of files if the already exists-v
/--verbose
: Show output
Usage
Take the following example:
HelloWorld.md
# Some title
Describing the following code... bla bla.
~~~~javascript tangle:helloWorld.js
console.log("Hello, world");
~~~~
By adding some css ...
~~~~css tangle:styles/button.css
#button1 {
border: none;
}
~~~~
By adding 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
$ ls
helloWorld.js HelloWorld.md styles
If one wishes to use Python 2, one could easily install
md-tangle2
instead.
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
Built Distribution
Hashes for md_tangle-1.0.1-py3-none-any.whl
Algorithm | Hash digest | |
---|---|---|
SHA256 | af89206edc459ff300fa15f0d00a493821839d9bdb92565f5c3a3b3f29b315ad |
|
MD5 | d4145eef7ad4719eb71daf398e2ea9c8 |
|
BLAKE2b-256 | d4dd53cdc25fd99ffdbb7eeb35c95a96a81e2a9b076080498000978f7862e131 |