| .gitignore | Initial commit | |
| LICENSE | initial commit | |
| README.md | had to fix the reference list in the footnotes for line breaks | |
| tangle.sh | there was an error whith && in code blocks, asked Euria to fix it... | |
tangle.sh
tangle is a literate programming/documenting utility that takes a markdown file and generates a code file from the code blocks it finds.
Use it in bash with tangle README.md. The markdown file should contain code blocks that have specific block attributes.
Example
The following creates a file, taking the filename from the attribute. You can include other code blocks through referencing them within double pointy brackets (which seems to be a standard in literate programming).
#!/bin/bash
output="Hello Kitty."
<<print-output>>
Now we define another code block. The .sh just let's your markdown editor know, what language is used in the code block, but it does't matter for the generation. The # is used to define the label for the block, which then can be referenced. Every code block can include other blocks, which would allow you to reuse a block several times as well.
echo "$output"
Tangling this readme with tangle README.md will produce the following script.
#!/bin/bash
output="Hello Kitty."
# From README.md:22 (block: print-output)
echo "$output"
tangle leaves behind some traces, from where in the markdown file it got a specific block. I used tangle to generate bash scripts for now, so the comment-style is hardcoded.
Attribution
The inspiration and need for this utility arose after a workshop with Ana Meisel [1], in which she offered a perspective on permacomputing [2], literate programming [3] and repair manuals [4], through leveraging the use of entangled [5] (among others). Following that, I wanted to have a simpler solution to generate the code files from a markdown file.
I vibe-coded this bash script through Euria [6], a LLM chatbot hosted in Switzerland, using Alibaba's Qwen3 model at the time of generation. I'm a little bit ashamed to be honest, but here we are.