md-tangle


Namemd-tangle JSON
Version 1.4.4 PyPI version JSON
download
home_pagehttps://github.com/joakimmj/md-tangle
SummaryGenerates ('tangles') source code from Markdown documents
upload_time2025-02-12 19:49:34
maintainerNone
docs_urlNone
authorJoakim Myrvoll Johansen
requires_pythonNone
licenseMIT
keywords markdown tangle literate programming
VCS
bugtrack_url
requirements No requirements were recorded.
Travis-CI No Travis.
coveralls test coverage No coveralls.
            [![app-badge]][PyPI-md-tangle] ![Version] ![License] ![Format] ![PyVer] ![Downloads]

# [md-tangle][PyPI-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][1] and [org-babel-tangle][2] in 
[Emacs][3] 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][4], and a more 
widely used document [markup language][5].

This way of programming is called [literate programming][6]. 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][7] 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][PyPI-md-tangle], 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`
```markdown
# 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:

```bash
$ 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][8] for `md-tangle` is of course written in Markdown, and tangles to the source
code.


[1]: https://en.wikipedia.org/wiki/Org-mode
[2]: https://orgmode.org/manual/Extracting-source-code.html
[3]: https://www.gnu.org/software/emacs/
[4]: https://en.wikipedia.org/wiki/Command-line_interface
[5]: https://en.wikipedia.org/wiki/Markup_language
[6]: https://en.wikipedia.org/wiki/Literate_programming
[7]: https://en.wikipedia.org/wiki/Markdown
[8]: https://github.com/joakimmj/md-tangle/blob/master/DOCS.md

[app-badge]: https://img.shields.io/badge/md--tangle-PyPI-orange.svg
[PyPI-md-tangle]: https://pypi.org/project/md-tangle
[Version]: https://img.shields.io/github/tag/joakimmj/md-tangle.svg?label=version
[License]: https://img.shields.io/github/license/joakimmj/md-tangle.svg
[Format]: https://img.shields.io/pypi/format/md_tangle.svg
[PyVer]: https://img.shields.io/pypi/pyversions/md-tangle.svg
[Downloads]: https://img.shields.io/pypi/dm/md-tangle.svg

            

Raw data

            {
    "_id": null,
    "home_page": "https://github.com/joakimmj/md-tangle",
    "name": "md-tangle",
    "maintainer": null,
    "docs_url": null,
    "requires_python": null,
    "maintainer_email": null,
    "keywords": "markdown, tangle, literate programming",
    "author": "Joakim Myrvoll Johansen",
    "author_email": "joakimmyrvoll@gmail.com",
    "download_url": null,
    "platform": "any",
    "description": "[![app-badge]][PyPI-md-tangle] ![Version] ![License] ![Format] ![PyVer] ![Downloads]\n\n# [md-tangle][PyPI-md-tangle]\nThis project is a result of wanting config and setup files to be part of a document \nexplaining my setup. I originally used [Org-mode][1] and [org-babel-tangle][2] in \n[Emacs][3] to achieve this. I really like Org-mode and Emacs, but I'm not fond of\nbeing dependent on one editor. This is the reason I wanted a [CLI][4], and a more \nwidely used document [markup language][5].\n\nThis way of programming is called [literate programming][6]. This programming paradigm \nwas introduced by Donald Knuth. The idea is to write a program as an explanation of the\nprogram logic in a natural language interspersed with snippets of traditional source code.\nThe source code can then be generated (\"tangled\") by using some tool.\n\nAs [Markdown][7] is used by most programmers, I saw that language fit for the task.\nMarkdown is a plaintext-ish format popular with programmers. It's simple, easy and \nalready has support for embedding code blocks using ``` or ~~~~, mostly \nfor the purposes of syntax highlighting in documentation.\n\n## Installing\nThis CLI tool can easily be utilized by adding `md-tangle` to your `PATH`, or by installing the package with `pip`.\n\nSee the package on [pypi.org][PyPI-md-tangle], or just install with `pip install md-tangle`.\n\n## Command\nBy adding the keyword `tangle:<path/filename>`, this tool will tangle tagged code\nblocks to given file. Supports `~` for home directory.\n\nOne can tangle the code block to multiple files by separating the files with chosen separator (default: `,`).\n\nIf the file already exists, the user will be prompted with the option to overwrite,\nunless the `-f`/`--force` flag is added.\n\n### Flags\n\n* `-h`/`--help`: Show help message and exit\n* `--version`: Show installed version\n* `-f`/`--force`: Force overwrite of files if the already exists\n* `-v`/`--verbose`: Show output\n* `-d`/`--destination`: Overwrite output destination\n* `-s`/`--separator`: Separator for tangle destinations (default=',')\n\n## Usage\n\nTake the following example:\n\n`HelloWorld.md`\n```markdown\n# Some title\nDescribing the following code... bla bla.\n\n~~~~javascript tangle:helloWorld.js\nconsole.log(\"Hello, \");\nconsole.log(\"world\");\n~~~~\n\n## Styling\nAdding header for my css files:\n\n~~~~css tangle:styles/button.css,styles/input.css\n/* Styling for mye awesome app */\n~~~~\n\nBy adding some css ... \n\n~~~~css tangle:styles/button.css\n#button1 {\n    border: none;\n}\n~~~~\n\n~~~~css tangle:styles/input.css\n#button1 {\n    border: none;\n}\n~~~~\n```\n\nBy installing `md-tangle` with `pip`, one could simply produce files from this file by executing:\n\n```bash\n$ md-tangle -v HelloWorld.md \nhelloWorld.js                                      2 lines\nstyles/button.css                                  4 lines\nstyles/input.css                                   4 lines\n$ ls \nhelloWorld.js HelloWorld.md styles\n```\n\n## Documentation\n\nThe [documentation][8] for `md-tangle` is of course written in Markdown, and tangles to the source\ncode.\n\n\n[1]: https://en.wikipedia.org/wiki/Org-mode\n[2]: https://orgmode.org/manual/Extracting-source-code.html\n[3]: https://www.gnu.org/software/emacs/\n[4]: https://en.wikipedia.org/wiki/Command-line_interface\n[5]: https://en.wikipedia.org/wiki/Markup_language\n[6]: https://en.wikipedia.org/wiki/Literate_programming\n[7]: https://en.wikipedia.org/wiki/Markdown\n[8]: https://github.com/joakimmj/md-tangle/blob/master/DOCS.md\n\n[app-badge]: https://img.shields.io/badge/md--tangle-PyPI-orange.svg\n[PyPI-md-tangle]: https://pypi.org/project/md-tangle\n[Version]: https://img.shields.io/github/tag/joakimmj/md-tangle.svg?label=version\n[License]: https://img.shields.io/github/license/joakimmj/md-tangle.svg\n[Format]: https://img.shields.io/pypi/format/md_tangle.svg\n[PyVer]: https://img.shields.io/pypi/pyversions/md-tangle.svg\n[Downloads]: https://img.shields.io/pypi/dm/md-tangle.svg\n",
    "bugtrack_url": null,
    "license": "MIT",
    "summary": "Generates ('tangles') source code from Markdown documents",
    "version": "1.4.4",
    "project_urls": {
        "Homepage": "https://github.com/joakimmj/md-tangle"
    },
    "split_keywords": [
        "markdown",
        " tangle",
        " literate programming"
    ],
    "urls": [
        {
            "comment_text": null,
            "digests": {
                "blake2b_256": "29a491c20be99dffa2938f8512b2c1e72dd9b44bf3dabf0783beeef4965fe430",
                "md5": "62ea637bb866a1f81ad358a4266fdc27",
                "sha256": "1480065c779b1c3971b0b8dfb7f7a33c54e7f02ae19b65caaf0ad2e7a6d82d46"
            },
            "downloads": -1,
            "filename": "md_tangle-1.4.4-py3-none-any.whl",
            "has_sig": false,
            "md5_digest": "62ea637bb866a1f81ad358a4266fdc27",
            "packagetype": "bdist_wheel",
            "python_version": "py3",
            "requires_python": null,
            "size": 6507,
            "upload_time": "2025-02-12T19:49:34",
            "upload_time_iso_8601": "2025-02-12T19:49:34.970598Z",
            "url": "https://files.pythonhosted.org/packages/29/a4/91c20be99dffa2938f8512b2c1e72dd9b44bf3dabf0783beeef4965fe430/md_tangle-1.4.4-py3-none-any.whl",
            "yanked": false,
            "yanked_reason": null
        }
    ],
    "upload_time": "2025-02-12 19:49:34",
    "github": true,
    "gitlab": false,
    "bitbucket": false,
    "codeberg": false,
    "github_user": "joakimmj",
    "github_project": "md-tangle",
    "travis_ci": false,
    "coveralls": false,
    "github_actions": false,
    "lcname": "md-tangle"
}
        
Elapsed time: 1.42240s