Entangled#

Entangled is a tool to manage code snippets in Markdown files. It allows you to tangle code from Markdown files into separate source files and stitch changes back into the Markdown files. For full documentation visit:

• user documentation
• installation / configuration.

Pandoc needs to be installed for Entangled.

VSCode extensions:

• Markdown All in One
• Markdown Preview Enhanced
• Entangled VSCode : helps for editing the entangled files.

Initial Installation#

Windows#

scoop install pandoc
uv pip install entangled-cli

Commands#

see: entangled --help
usage: entangled [-h] [-d] [-v] {tangle,stitch,sync,watch,status} ...

positional arguments: {tangle,stitch,sync,watch,status}

tangle
Tangle codes from Markdown
[-h] help, [-s] only show, [--force] force tangle
[-r] rebuild file data base

stitch
Stitch code changes back into the Markdown
[-h] help, [--force] force stitch, [-s] only show

sync : Be smart wether to tangle or stich

watch : Keep a loop running, watching for changes, then 'sync'
! does not work on windows !
replaced by 'winwatch.ps1':
- watches changes on markdown file in \doc + main.py
- triggers a 'entangled sync' on these files change
- documented inside the file

status : show status of watched / updated files

options :

-h, --help            show this help message and exit  
-d, --debug           enable debug messages  
-v, --version         show version number  

Entangled conflicts after merging branches#

Entangled can get confused when you merge, and there is a conflict on .entangled/filedb.json. This file keeps track of which files are sources for Entangled and which ones are generated by Entangled. That way, Entangled will never overwrite files it isn't supposed to, and the other way around, when you rename a target, the old one gets removed. It is very hard to merge this file though. When you need to, you can regenerate this file using:

entangled tangle -r

Restoring files when both Markdown and code have changed#

When you edited both Markdown and code without the daemon running, you may need to do some tricks to get back into a consistent state.

git add . 
git commit -m 'fixed everything'  # save everything you did
entangled tangle --force          # overwrites some changes you made
git restore main.py               # retrieve from latest commit
entangled stitch                  # apply changes back to markdown
git add .
git commit --amend                # amend your commit to perfection

Configuration#

version = "2.0"
watch_list = ["docs/**/*.md"]
hooks = ["build"]

#[markers]
#open="^(?P<indent>\\s*)```(?P<properties>.*)$"
#close="^(?P<indent>\\s*)```\\s*$"

[[languages]]
name = "Powershell"
identifiers =  ["powershell", "pwsh"]
comment = { open = "#" }

[[languages]]
name = "XML"
identifiers = ["xml", "html", "svg"]
comment = { open = "<!--", close = "-->" }

[[languages]]
name = "mermaid"
identifiers =  ["mermaid"]
comment = { open = "%%" }

[[languages]]
name = "yaml"
identifiers =  ["yaml"]
comment = { open = "#" }

[[languages]]
name = "toml"
identifiers =  ["toml"]
comment = { open = "#" }