major revision; uses more routines in Entangled itself to read and manipulate markdown; include filter for repl-session

Author: jhidding

.entangled/build/Makefile

@@ -0,0 +1,8 @@
+
+# This Makefile is generated by Entangled. Modifications will be overwritten.
+
+.PHONY = all
+
+all: 
+
+

.entangled/filedb.json

@@ -1,44 +1,56 @@
 {
-  "version": "2.0.0-alpha-3",
   "files": [
     {
-      "path": "README.md",
       "deps": null,
-      "modified": "2023-05-20T15:45:38.374816",
-      "hexdigest": "dead468bea87407e2e6a7b229e76c812a231e0f6289eddf171ba8bd0534e364c"
+      "hexdigest": "5a199ccde2b8e71f83105c9c8d8991a2330abc5cfc35ecaddc99202a0126f616",
+      "modified": "2025-10-03T14:12:18.980572",
+      "path": "docs/index.md",
+      "size": 1444
     },
     {
-      "path": "docs/setup.md",
       "deps": null,
-      "modified": "2023-05-21T19:42:18.759752",
-      "hexdigest": "e56cec2fb11ac9540a06a92996e6b9ac6424c699dc1e6d6f33138f243a94d949"
+      "hexdigest": "aca9aaefe77198c38904af9b3b10b40cec5f6ccdab88630ccf634e5d09d1cff3",
+      "modified": "2025-10-03T14:11:22.118375",
+      "path": "docs/setup.md",
+      "size": 8610
     },
     {
-      "path": "examples/hello_world.py",
       "deps": [
-        "docs/index.md"
+        "docs/setup.md"
       ],
-      "modified": "2023-05-20T15:50:49.652413",
-      "hexdigest": "66e79b50c625e5edddbe3e1c1222b74ce0e5f776abc43ea6366816544219fc45"
+      "hexdigest": "92862e6cb986fb6bed9b6c74cb54af86ccfd80d0e245af0569905ce005b3b92a",
+      "modified": "2025-10-03T14:11:28.015952",
+      "path": "examples/entangled.toml",
+      "size": 382
     },
     {
-      "path": "docs/index.md",
-      "deps": null,
-      "modified": "2023-05-20T22:25:25.108970",
-      "hexdigest": "860d6dfc07cd8246a7fdb0c425eb6217677ef9006f84693c630b4faaf90bfcce"
-    },
-    {
-      "path": "examples/plot.gp",
       "deps": [
         "docs/index.md"
       ],
-      "modified": "2023-05-20T22:13:50.926594",
-      "hexdigest": "e0a44680408c7b2b7c4fec1551d0a6a835df6ecd0c1d68a758b43c2ef89ea29e"
+      "hexdigest": "66e79b50c625e5edddbe3e1c1222b74ce0e5f776abc43ea6366816544219fc45",
+      "modified": "2025-10-03T13:40:25.520753",
+      "path": "examples/hello_world.py",
+      "size": 189
+    },
+    {
+      "deps": [],
+      "hexdigest": "320ddf2659f09b1f60a03408016487064e8b3754fa96a4355ad6a7b9bbec553c",
+      "modified": "2025-10-03T14:11:28.024507",
+      "path": "examples/lua-session.json",
+      "size": 545
+    },
+    {
+      "deps": [],
+      "hexdigest": "ca3da004e36b672abfbee4274ce33486ab6c7cd6585c3830dc55eb0582629a06",
+      "modified": "2025-10-03T13:42:28.370463",
+      "path": "test/lua-session.json",
+      "size": 546
     }
   ],
   "source": [],
   "target": [
-    "examples/plot.gp",
+    "examples/entangled.toml",
     "examples/hello_world.py"
-  ]
+  ],
+  "version": "2.2.0"
 }

.github/workflows/python-package.yml

@@ -32,6 +32,3 @@ jobs:
     - name: Run typechecker
       run: |
         poetry run mypy
-    - name: Test with pytest
-      run: |
-        poetry run pytest

docs/index.md

@@ -13,23 +13,25 @@ plugins:
   - entangled  # this also runs `entangled sync` as a pre-build action
 
 markdown_extensions:
+  - attr_list
   - pymdownx.superfences
   - pymdownx.tabbed:
-      alternate_style: true 
+      alternate_style: true
 ```
 
 Also create `entangled.toml`, the `version` field is obligatory.
 
 ```toml
 version = "2.0"
 watch_list = ["docs/**/*.md"]
-hooks = ["build"]
+hooks = ["repl"]
 ```
 
 ## Components
 This plugin bundles functionality for literate programming with Entangled.
 
 - Annotate code blocks with titles.
+- Insert results from `repl-session`.
 
 ### Annotate code blocks
 The default markdown syntax that Entangled supports has fenced code blocks as follows

docs/setup.md

@@ -1,5 +1,5 @@
 # Setup instructions for MkDocs with Entangled
-If you'd like to use Entangled together with MkDocs, here's an opiniated guide (if you have differing opinions, you'll know howto adapt). 
+If you'd like to use Entangled together with MkDocs, here's an opiniated guide.
 
 ## Python and MkDocs
 Start with an empty project folder, say `my-awesome-project`.
@@ -10,18 +10,17 @@ cd my_awesome_project
 git init
 ```
 
-You may want to setup a virtual environment to install MkDocs into. Even if your project is not Python related, it pays to have a reproducible build environment for your documentation. I use [Poetry](https://python-poetry.org/) to manage my environments.
+You may want to setup a virtual environment to install MkDocs into. Even if your project is not Python related, it pays to have a reproducible build environment for your documentation. I use [`uv`](https://docs.astral.sh/uv/) to manage my environments.
 
-```sh
-poetry init
-# <<follow the gentle instructions>>
-poetry add -D mkdocs mkdocs-material entangled-cli[rich] mkdocs-entangled-plugin
-poetry shell
+```bash
+uv init --bare
+uv add -D mkdocs mkdocs-material entangled-cli mkdocs-entangled-plugin
+uv sync
+source .venv/bin/activate
 ```
 
-Using virtual environments will take up some disk space. With these moderate requirements however, we're still under 200 MB.
-
-Next we initialize, configure, and run MkDocs. 
+Now you have created a virtual environment using UV and activated it (alas there is no `uv shell` command that I know of).
+Next we initialize, configure, and run MkDocs.
 
 ```sh
 mkdocs new .
@@ -38,13 +37,14 @@ plugins:
   - entangled
 
 markdown_extensions:
+  - attr_list
   - pymdownx.superfences
 
 theme:
   name: material
 ```
 
-This sets the title, repo name and a toggle for dark mode viewing. the `entangled` plugin needs `pymdownx.superfences` to be enabled.
+This sets the title, repo name and a toggle for dark mode viewing. the `entangled` plugin expects the `attr_list` and `pymdownx.superfences` markdown extensions to be enabled.
 Make sure to check out [MkDocs Material](https://squidfunk.github.io/mkdocs-material/) for more documentation on configuring MkDocs with Material.
 
 ```sh
@@ -56,25 +56,21 @@ This will start a build loop and web server. That means that every time one of t
 ## Setup Entangled
 Entangled will work without any additional configuration in `entangled.toml`. The default config monitors the entire source repository for Markdown files. Files that are extracted from the Markdown are also watched for changes. If you'd like to limit the scope of Markdown files that are monitored, you can set `watch_list` to a list of glob patterns. For MkDocs projects it makes sense to set `watch_list = [ "docs/**/*.md" ]`.
 
-To enable building artifacts add the `build` hook, by setting `hooks = ["build"]`.
+We will also demo the `repl` hook for Entangled later on.
 
 The complete configuration then looks like this:
 
 ``` {.toml file=examples/entangled.toml}
 version = "2.0"
 watch_list = ["docs/**/*.md"]
-hooks = ["build"]
-```
-
-Entangled runs as a pre-build action in MkDocs. So, you may want to add your generated source files in the watch list of MkDocs. Assuming your source files are in `./src`:
+hooks = ["repl"]
 
-```yaml
-watch:
-  - docs
-  - src
+<<repl-config>>
 ```
 
 ## Extras
+Some extras.
+
 ### Syntax Highlighting
 Add the following to the `markdown_extensions` section in `mkdocs.yml`:
 
@@ -88,6 +84,45 @@ markdown_extensions:
       pygments_lang_class: true
 ```
 
+### Evaluating a REPL session
+When you write documentation or teaching material it can be nice to automatically evaluate commands in a REPL and show the results in your rendered output. Entangled ships with a command-line tool `repl-session` that evaluates a series of commands in a configured REPL. Both input and output are JSON data.
+Entangled contains a hook that integrates with `repl-session`.
+
+For each language you need to configure the REPL in `entangled.toml` in the `[hook.repl.config.<language>]` section. For example,
+
+``` {toml #repl-config}
+[hook.repl.config.Lua]
+command = "lua"
+first_prompt = "> "
+change_prompt = '_PROMPT = "{key}> "; _PROMPT2 = "{key}+ "'
+prompt = "{key}> "
+continuation_prompt = "{key}\\+ "
+strip_ansi = true
+```
+
+Each repl block must be attached to a session, which is the JSON file to which the session is written. It is the responsibility of the user to make sure, with whatever build system tool (say GNU Make or Brei), that the resulting JSON file is passed through `repl-session` to a file in the same directory with the `out.json` extension. This way, the REPL session will only be rerun when the session file changes.
+
+Did you know that Lua supports tail-call elimination? We can define a factorial function,
+
+``` {.lua .repl #lua-repl session=examples/lua-session.json}
+function fac(n, m)
+    if m == nil then
+        return fac(n, 1)
+    end
+    if n == 0 then
+        return m
+    else
+        return fac(n-1, m*n)
+    end
+end
+```
+
+and this runs in constant stack space!
+
+``` {.lua .repl #lua-repl}
+fac(63)
+```
+
 ### Equations using Mathjax
 A common requirement is to have support for equations. Add the following to your `mkdocs.yml`
 
@@ -132,11 +167,11 @@ You can enable a dark-mode toggle by adding to your `mkdocs.yml`
 ```yaml
 theme:
   name: material
-  palette: 
+  palette:
     # Palette toggle for light mode
     - scheme: default
       toggle:
-        icon: material/brightness-7 
+        icon: material/brightness-7
         name: Switch to dark mode
 
     # Palette toggle for dark mode
@@ -151,60 +186,77 @@ You may want to use Github Actions to deploy the website. I use the following `.
 
 <details><summary>Deploy Pages action</summary>
 
+Note from two years later: Github Actions are extraordinarily fickle and require constant maintenance. Always make sure that you update to the newest versions. This version is from October 2025:
+
 ```yaml
-name: Deploy Pages
+name: Deploy pages
 
 # Controls when the workflow will run
 on:
   # Triggers the workflow on push or pull request events but only for the "main" branch
   push:
-    branches: [ "main" ]
+    branches: ["main"]
 
   # Allows you to run this workflow manually from the Actions tab
   workflow_dispatch:
 
-# Sets permissions of the GITHUB_TOKEN to allow deployment to GitHub Pages
 permissions:
   contents: read
   pages: write
   id-token: write
 
+# Allow only one concurrent deployment, skipping runs queued between the run in-progress and latest queued.
+# However, do NOT cancel in-progress runs as we want to allow these production deployments to complete.
+concurrency:
+  group: "pages"
+  cancel-in-progress: false
+
+# A workflow run is made up of one or more jobs that can run sequentially or in parallel
 jobs:
+  # This workflow contains a single job called "build"
   build:
-    environment:
-      name: github-pages
-      url: ${{ steps.deployment.outputs.page_url }}
     # The type of runner that the job will run on
     runs-on: ubuntu-latest
 
     # Steps represent a sequence of tasks that will be executed as part of the job
     steps:
       # Checks-out your repository under $GITHUB_WORKSPACE, so your job can access it
-      - uses: actions/checkout@v3
+      - uses: actions/checkout@v4
+
+      - name: Install uv
+        uses: astral-sh/setup-uv@v6
 
-      - name: Install 
-        run: |
-          pip install poetry
-          poetry install
+      - name: Install dependencies
+        run: uv sync
+
+      - name: Run MkDocs
+        run: uv run mkdocs build
+
+      - name: Configure GitHub Pages
+        uses: actions/configure-pages@v5
 
-      - name: Generate site
-        run: poetry run mkdocs build
-  
       - name: Upload artifact
-        uses: actions/upload-pages-artifact@v1
+        uses: actions/upload-pages-artifact@v4
         with:
-          path: 'site'
+          path: "site"
 
+  deploy:
+    environment:
+      name: github-pages
+      url: ${{ steps.deployment.outputs.page_url }}
+    runs-on: ubuntu-latest
+    needs: build
+    steps:
       - name: Deploy to GitHub Pages
         id: deployment
-        uses: actions/deploy-pages@v2
+        uses: actions/deploy-pages@v4
 ```
 
 </details>
 
 ## Commit
-Don't forget to create a `README.md`, `LICENSE`, and later on a `CITATION.cff`. You may want to add `poetry.lock` to `.gitignore`.
-You should be good to go! A fresh Entangled/MkDocs project should have the following files:
+Don't forget to create a `README.md`, `LICENSE`, and later on a `CITATION.cff`.
+A fresh Entangled/MkDocs project should have the following files:
 
 ```
 .
@@ -225,7 +277,7 @@ Create a home for your new project and push.
 ```sh
 git add .
 git commit -m 'initial commit'
-git remote add origin git@github.com:joeplummer/my-awesome-project.git
+git remote add origin git@github.com:johndoe/my-awesome-project.git
 git push -u origin main
 ```
 

entangled.toml

@@ -1,3 +1,11 @@
 version = "2.0"
 watch_list = ["docs/**/*.md"]
-hooks = ["build"]
+hooks = ["build", "repl"]
+
+[hook.repl.config.Lua]
+command = "lua"
+first_prompt = "> "
+change_prompt = '_PROMPT = "{key}> "; _PROMPT2 = "{key}+ "'
+prompt = "{key}> "
+continuation_prompt = "{key}\\+ "
+strip_ansi = true

examples/entangled.toml

@@ -0,0 +1,15 @@
+# ~/~ begin <<docs/setup.md#examples/entangled.toml>>[init]
+version = "2.0"
+watch_list = ["docs/**/*.md"]
+hooks = ["repl"]
+
+# ~/~ begin <<docs/setup.md#repl-config>>[init]
+[hook.repl.config.Lua]
+command = "lua"
+first_prompt = "> "
+change_prompt = '_PROMPT = "{key}> "; _PROMPT2 = "{key}+ "'
+prompt = "{key}> "
+continuation_prompt = "{key}\\+ "
+strip_ansi = true
+# ~/~ end
+# ~/~ end