mdeval 1.3.1 → 1.5.0

package/README.md

@@ -9,6 +9,9 @@ mdeval embeds JavaScript directly in your Markdown using HTML comments. The logi
 
 Any value that matters — a dependency count, a version string, a benchmark result — is computed, not typed. Whether written by a person or an AI agent, the expression shows the work and anyone can verify it. Re-run `mdeval` and every value updates.
 
+> [!TIP]
+> Particularly useful for **knowledge bases** — contact lists, project trackers, changelogs, or any Markdown that functions as a source of truth. Values stay accurate on every run, so nothing drifts. AI agents reading the files also benefit: pre-computed values mean they don't need to re-process raw data across multiple documents, cutting token usage significantly.
+
 ## Install
 
 ```bash
@@ -28,7 +31,12 @@ const pkg = JSON.parse(await fs.readFile('package.json', 'utf8'));
 -->
 ```
 
-Full Node.js, ESM imports, top-level `await`, and shell commands via [`$`](https://google.github.io/zx/) are supported.
+Script blocks support:
+
+- Full Node.js — any built-in module or installed package
+- ESM `import` / `export`
+- Top-level `await`
+- Shell commands via [`$`](https://google.github.io/zx/)
 
 A **value marker** is where the result appears. It starts with `<!--mdeval ` (with a space) followed by a JavaScript expression:
 
@@ -46,11 +54,136 @@ The file is updated in-place. You can pass multiple files or glob patterns: `mde
 
 `node_modules` and hidden directories are automatically excluded from glob expansion.
 
+## Example
+
+**`CONTACTS.md`** — a contact list stored as data, rendered as a table when viewed:
+
+````markdown
+<!--mdeval
+import { table, link } from 'md-pen';
+
+export const contacts = [
+  {
+    name: 'Alice Martin',
+    linkedin: 'https://linkedin.com/in/alice-martin',
+    notes: 'Met at JSConf 2023',
+  },
+  {
+    name: 'Bob Tanaka',
+    linkedin: 'https://linkedin.com/in/bob-tanaka',
+    notes: 'Former colleague at Acme Co.',
+  },
+];
+
+export const findContact = name => contacts.find(c => c.name === name);
+
+const contactsTable = table(
+  contacts.map(({ name, linkedin, notes }) => ({ Name: link(linkedin, name), Notes: notes })),
+);
+-->
+
+<!--mdeval block(contactsTable)-->
+| Name | Notes |
+| - | - |
+| [Alice Martin](https://linkedin.com/in/alice-martin) | Met at JSConf 2023 |
+| [Bob Tanaka](https://linkedin.com/in/bob-tanaka) | Former colleague at Acme Co. |
+<!--/mdeval-->
+````
+
+**`TIMELINE.md`** — imports contacts and links them by LinkedIn:
+
+````markdown
+<!--mdeval
+import { link, ul, bold } from 'md-pen';
+
+// Imports from the mdeval block!
+import { findContact } from './CONTACTS.md';
+
+const events = [
+  { date: '2023-10-15', description: 'Attended JSConf 2023' },
+  { date: '2024-03-01', description: `Coffee with ${link(findContact('Alice Martin').linkedin, 'Alice Martin')}` },
+  { date: '2024-11-08', description: 'Started new open-source project' },
+];
+
+const list = ul(events.map(({ date, description }) => `${bold(date)} — ${description}`));
+-->
+
+<!--mdeval block(list)-->
+- __2023-10-15__ — Attended JSConf 2023
+- __2024-03-01__ — Coffee with [Alice Martin](https://linkedin.com/in/alice-martin)
+- __2024-11-08__ — Started new open-source project
+<!--/mdeval-->
+````
+
+The source of truth for contacts live in `CONTACTS.md`. If contact info changes, run `mdeval **/*.md` and all files get re-rendered with the latest data.
+
+## Helpers
+
+mdeval ships two helpers used in markers:
+
+| Helper | Description |
+|--------|-------------|
+| `block(value)` | Wraps the value with surrounding newlines so block-level Markdown (headings, lists, tables) renders correctly |
+| `$` | [zx](https://google.github.io/zx/) shell — run commands via tagged templates |
+
+How you access them depends on the file extension:
+
+| File | Access |
+|------|--------|
+| `.md` | Available as globals — call directly: `block(x)` or `` $`cmd` `` |
+| `.js`, `.ts`, anything else | Import explicitly: `import { block, $ } from 'mdeval'` |
+
+The `.md` case works because the CLI (and `--import mdeval/loader`) seeds the helpers on `globalThis` at startup. Modules imported transitively from a `.md` see them too, but in non-`.md` files prefer the explicit import for clarity and portability. The plain `import { block, $ } from 'mdeval'` is side-effect-free — no globals are touched, no loader is registered.
+
+## Using `.md` exports from a script
+
+`.md` files with mdeval script blocks are real ESM modules — anything they `export` can be imported from a Node script. Useful for validation tools, migration scripts, or any code that needs to read structured data out of a Markdown knowledge base.
+
+Run your script with `--import mdeval/loader`:
+
+```bash
+node --import mdeval/loader ./consumer.js
+```
+
+`consumer.js` can then use ordinary static imports against `.md` files:
+
+```js
+import { todos } from './TODOS.md'
+
+console.log(todos)
+```
+
+`--import mdeval/loader` is a side-effect-only entry. Before any of `consumer.js`'s imports are linked, it seeds `block` and `$` on `globalThis` and registers the Node ESM loader so `.md` files resolve as modules. Without it, the static `import` of a `.md` fails — Node has no idea how to load `.md` yet.
+
+The plain `mdeval` import stays pure — `import { block, $ } from 'mdeval'` just gives you the helpers without touching `globalThis` or registering any loader. The split keeps "I want the helpers in my script" separate from "I want to load `.md` files".
+
+You can also point `--import mdeval/loader` at a `.md` file directly:
+
+```bash
+node --import mdeval/loader ./TODOS.md
+```
+
+Runtime stack traces from a `.md` point at original lines and columns — the loader sets up source maps automatically.
+
 ## Notes
 
 - A file can have **multiple script blocks** — they're merged into one module, so variables and imports are shared. We recommend placing them at the top to signal the file has generated content.
 
-- Markers can be **self-contained** — no script block needed:
+- **Markers can span multiple lines.** Don't cram everything into one line — give the expression room to breathe. This is what makes inlining marker-specific logic next to its output practical:
+
+  ```markdown
+  <!--mdeval block(table([
+    { name: 'cleye', version: '^2.3.0' },
+    { name: 'md-pen', version: '^0.0.2' },
+  ]))-->
+  | Package | Version |
+  | - | - |
+  | cleye | ^2.3.0 |
+  | md-pen | ^0.0.2 |
+  <!--/mdeval-->
+  ```
+
+  When the expression needs statements or control flow, wrap it in an IIFE:
 
   ```markdown
   <!--mdeval (() => {
@@ -60,18 +193,14 @@ The file is updated in-place. You can pass multiple files or glob patterns: `mde
   })()-->odd<!--/mdeval-->
   ```
 
-  In large documents, this IIFE pattern lets you keep logic next to the marker it serves instead of in a distant script block.
-
-- Marker expressions are **auto-awaited** — promises resolve automatically, so you can use `fetch()` or any async API directly in a marker without wrapping it in a script block.
+  Coupling the expression to its rendered value keeps related code together and reads better than pushing every variable into a distant script block. Reserve script blocks for shared imports or values referenced by multiple markers.
 
-- **`$`** from [zx](https://google.github.io/zx/) is available as a global — run shell commands directly in markers:
+- Marker expressions are **auto-awaited** — promises resolve automatically. Async APIs work directly in a marker without a script block:
 
   ```markdown
-  <!--mdeval $`git branch --show-current`-->main<!--/mdeval-->
+  Status: <!--mdeval (await fetch('https://api.github.com/repos/privatenumber/mdeval')).status-->200<!--/mdeval-->
   ```
 
-- If your value starts with a heading, list, or other block element, wrap it with **`block()`** so it renders on its own line. `block()` is a global helper that adds newlines before and after the value.
-
 - You can **import from other `.md` files**. Only the script blocks are executed — no markers are processed:
 
   ```markdown
@@ -82,6 +211,15 @@ The file is updated in-place. You can pass multiple files or glob patterns: `mde
 
   This lets you share constants and logic across multiple markdown files.
 
+  If the imported file might not yet have mdeval content (e.g. a stub being filled in over time), use a **namespace import** so missing exports resolve to `undefined` instead of crashing Node's ESM linker:
+
+  ```markdown
+  <!--mdeval
+  import * as data from './stub.md';
+  const version = data.version ?? 'tbd';
+  -->
+  ```
+
 - When processing multiple files (`mdeval a.md b.md`), all files **share the same Node.js runtime** — including the module cache, `globalThis`, and `process.env`. This is the same behavior as any Node.js program using `import()`.
 
 ## Caveats
@@ -115,6 +253,29 @@ const depsTable = table(deps.map(([name, version]) => [
 <!--/mdeval-->
 ```
 
+## Git hook
+
+Run mdeval automatically before every commit so values never go stale. [Lefthook](https://github.com/evilmartians/lefthook) makes this easy:
+
+```sh
+npm install lefthook --save-dev
+```
+
+```yaml
+# lefthook.yml
+pre-commit:
+  jobs:
+    - name: mdeval
+      # lefthook's default `gobwas` matcher requires `**` to span 1+ dirs,
+      # so `**/*.md` alone misses root-level files like README.md
+      glob: ["*.md", "**/*.md"]
+      run: |
+        files=$(npx mdeval "**/*.md")
+        [ -n "$files" ] && git add $files
+```
+
+`glob` makes the hook a no-op when no Markdown files are staged. mdeval prints the path of each file it rewrites to stdout, so `git add $files` re-stages only the files it actually updated. Note: `$files` relies on shell word-splitting, so this assumes `.md` paths without spaces.
+
 ## Agent Skills
 
 This package ships with a built-in [agent skill](./skills/mdeval/SKILL.md) for AI coding assistants. Set up [`skills-npm`](https://github.com/antfu/skills-npm) to automatically discover it.

package/dist/cli.mjs

@@ -1,5 +1,3 @@
 #!/usr/bin/env node
-var M=Object.defineProperty;var p=(o,r)=>M(o,"name",{value:r,configurable:!0});import m from"node:fs/promises";import $ from"node:path";import{cli as b}from"cleye";import{glob as x}from"tinyglobby";import{$ as S}from"zx";import{p as d,b as O,E as _,M as f,C as k,a as g,c as C,i as P}from"./parse-markdown-B18EMsYy.mjs";import{register as R}from"node:module";import{pathToFileURL as T}from"node:url";import"micromark";const N=p(o=>{if(o==null)throw new Error(`Cannot interpolate ${o} \u2014 this is likely a bug in your script`);return typeof o=="string"?o:typeof o=="object"?Symbol.toPrimitive in o?String(o):JSON.stringify(o):String(o)},"coerceValue");R("#md-loader",import.meta.url);const v=p(async(o,r)=>{const{markers:t}=d(o);if(t.length===0)return o;const i=await import(T(r).href),n=O(t),w=await Promise.all(Array.from(n).map(async([e,l])=>{const s=N(await i[`${_}${l}`]);if(s.includes(f)||s.includes(`${k}
-`)||s.includes(g))throw new Error(`Expression "${e}" produced a value containing mdeval comment syntax, which would corrupt the document on re-parse`);return s})),a=[];let c=0;for(const e of t){const l=f.length+e.expression.length+C.length,s=e.start+l,E=e.end-g.length,y=n.get(e.expression);a.push(o.slice(c,s),w[y]),c=E}return a.push(o.slice(c)),a.join("")},"processSource");globalThis.block=o=>`
-${String(o)}
-`,globalThis.$=S;const A=b({name:"mdeval",parameters:["<files...>"]}),u=A._.files,F=u.some(o=>o.includes("node_modules")),h=await x(u,{ignore:F?[]:["**/node_modules/**"]});h.length===0&&(console.error("No files matched the given patterns"),process.exit(1)),await Promise.all(h.map(async o=>{try{const r=$.resolve(o),t=await m.readFile(r,"utf8"),i=d(t);P(t,i)&&console.warn(`Warning: ${o} has no markdown content outside of mdeval blocks`);const n=await v(t,r);n!==t&&(await m.writeFile(r,n,"utf8"),console.log(`Updated: ${o}`))}catch(r){console.error(`Error processing ${o}:`,r instanceof Error?r.message:r),process.exitCode=1}}));
+var M=Object.defineProperty;var l=(o,r)=>M(o,"name",{value:r,configurable:!0});import m from"node:fs/promises";import x from"node:path";import{cli as O}from"cleye";import{glob as S}from"tinyglobby";import"./loader.mjs";import{p as d,b as _,E as b,M as f,C,a as u,c as P,i as R}from"./parse-markdown-wnFVEAED.mjs";import{pathToFileURL as $}from"node:url";import"node:module";import"./runtime.mjs";import"zx";import"micromark";const k=l(o=>{if(o==null)throw new Error(`Cannot interpolate ${o} \u2014 this is likely a bug in your script`);return typeof o=="string"?o:typeof o=="object"?Symbol.toPrimitive in o?String(o):JSON.stringify(o):String(o)},"coerceValue"),N=l(async(o,r)=>{const{markers:t}=d(o);if(t.length===0)return o;const i=await import($(r).href),n=_(t),w=await Promise.all(Array.from(n).map(async([e,p])=>{const s=k(await i[`${b}${p}`]);if(s.includes(f)||s.includes(`${C}
+`)||s.includes(u))throw new Error(`Expression "${e}" produced a value containing mdeval comment syntax, which would corrupt the document on re-parse`);return s})),a=[];let c=0;for(const e of t){const p=f.length+e.expression.length+P.length,s=e.start+p,E=e.end-u.length,y=n.get(e.expression);a.push(o.slice(c,s),w[y]),c=E}return a.push(o.slice(c)),a.join("")},"processSource"),T=O({name:"mdeval",parameters:["<files...>"]}),g=T._.files,v=g.some(o=>o.includes("node_modules")),h=await S(g,{ignore:v?[]:["**/node_modules/**"]});h.length===0&&(console.error("No files matched the given patterns"),process.exit(1)),await Promise.all(h.map(async o=>{try{const r=x.resolve(o),t=await m.readFile(r,"utf8"),i=d(t);R(t,i)&&console.warn(`Warning: ${o} has no markdown content outside of mdeval blocks`);const n=await N(t,r);n!==t&&(await m.writeFile(r,n,"utf8"),console.log(o))}catch(r){console.error(`Error processing ${o}:`,r instanceof Error?r.message:r),process.exitCode=1}}));

package/dist/loader.mjs

@@ -0,0 +1,2 @@
+#!/usr/bin/env node
+import{register as r}from"node:module";import{block as o}from"./runtime.mjs";import{$ as e}from"zx";Object.assign(globalThis,{block:o,$:e}),process.setSourceMapsEnabled(!0),r("#md-loader",import.meta.url);

package/dist/md-loader.mjs

@@ -1,5 +1,12 @@
 #!/usr/bin/env node
-var p=Object.defineProperty;var i=(r,o)=>p(r,"name",{value:o,configurable:!0});import c from"node:fs/promises";import{fileURLToPath as m}from"node:url";import{p as f,b as u,E as d}from"./parse-markdown-B18EMsYy.mjs";import"micromark";const l=i((r,o)=>{const e=r.map(t=>t.content).join(`
-`),s=u(o);if(s.size===0)return e;const n=[...s].map(([t,a])=>`export const ${d}${a} = ${t};`);return`${e}
-${n.join(`
-`)}`},"generateModule"),$=i(async(r,o,e)=>{if(!r.endsWith(".md"))return e(r,o);const s=await c.readFile(m(r),"utf8"),{scriptBlocks:n,markers:t}=f(s);return n.length===0&&t.length===0?e(r,o):{format:"module",source:l(n,t),shortCircuit:!0}},"load");export{$ as load};
+var x=Object.defineProperty;var c=(e,a)=>x(e,"name",{value:a,configurable:!0});import b from"node:fs/promises";import{pathToFileURL as E,fileURLToPath as T}from"node:url";import{p as $,E as B,M as F}from"./parse-markdown-wnFVEAED.mjs";import{GenMapping as P,toEncodedMap as W,addSegment as U}from"@jridgewell/gen-mapping";import"micromark";const M=10,v=13,N=c(e=>e===9||e===M||e===11||e===12||e===v||e===32,"isWhitespaceCode"),j=c(e=>e>=48&&e<=57||e>=65&&e<=90||e===95||e>=97&&e<=122||e===36,"isIdentifierCode"),A=c((e,a)=>{const h=E(e).href,p=new P({file:e}),s=[];let i="";const o=[];for(let n=a.indexOf(`
+`);n!==-1;n=a.indexOf(`
+`,n+1))o.push(n);const y=c(n=>{let t=0,r=o.length;for(;t<r;){const f=Math.floor((t+r)/2);o[f]<n?t=f+1:r=f}const d=t>0?o[t-1]:-1;return{line:t,column:n-d-1}},"positionFromOffset"),u=c(n=>{i+=n},"appendLineChunk"),S=c(()=>{s.push(i),i=""},"flushLine"),O=c((n,t)=>{const r=y(t);let d=r.line,f=r.column,L=!1,R=!1,m=0;const w=c(l=>i.length+l-m,"generatedColumn");for(let l=0;l<n.length;l+=1){const g=n.codePointAt(l),C=N(g),I=j(g);!C&&(l===0||R||!L||!I)&&U(p,s.length,w(l),h,d,f),g===M?(d+=1,f=0):f+=1,L=I,R=C,g===M&&(u(n.slice(m,l)),S(),m=l+1)}m<n.length&&u(n.slice(m))},"appendSourceText"),k=c(n=>{let t=0;for(let r=n.indexOf(`
+`);r!==-1;r=n.indexOf(`
+`,t))u(n.slice(t,r)),S(),t=r+1;t<n.length&&u(n.slice(t))},"appendSyntheticText");return{appendSource(n,t){O(n,t)},appendSynthetic(n){k(n)},toModuleSource:c(()=>{const t=`${(i===""?s:[...s,i]).join(`
+`)}
+`,r=W(p),d=`//# sourceMappingURL=data:application/json;base64,${Buffer.from(JSON.stringify(r)).toString("base64")}`;return`${t}${d}
+`},"toModuleSource")}},"createSourceBuilder"),X=c((e,a,h,p)=>{const s=A(a,e);for(const o of h)s.appendSource(o.content,o.contentStart),o.content.endsWith(`
+`)||s.appendSynthetic(`
+`);const i=new Map;for(const o of p)i.has(o.expression)||i.set(o.expression,{index:i.size,marker:o});for(const[o,{index:y,marker:u}]of i){const S=`export const ${B}${y} = `;s.appendSynthetic(S),s.appendSource(o,u.start+F.length),s.appendSynthetic(`;
+`)}return s.toModuleSource()},"generateModule"),_=c(async(e,a,h)=>{if(!e.endsWith(".md"))return h(e,a);const p=T(e),s=await b.readFile(p,"utf8"),{scriptBlocks:i,markers:o}=$(s);return i.length===0&&o.length===0?{format:"module",source:"",shortCircuit:!0}:{format:"module",source:X(s,p,i,o),shortCircuit:!0}},"load");export{_ as load};

package/dist/parse-markdown-wnFVEAED.mjs

@@ -0,0 +1,6 @@
+var M=Object.defineProperty;var l=(n,e)=>M(n,"name",{value:e,configurable:!0});import{postprocess as v,parse as w,preprocess as k}from"micromark";const x="mdeval",c=`<!--${x}`,C=`${c} `,E=`<!--/${x}-->`,b=`__${x}_`,g="-->",_=l(n=>{const e=new Map;for(const{expression:s}of n)e.has(s)||e.set(s,e.size);return e},"buildExpressionMap"),$=l(n=>{const e=n.codePointAt(0)===65279?1:0,s=v(w().document().write(k()(n,void 0,!0))),r=[];for(const[o,t]of s)o==="enter"&&(t.type==="codeFenced"||t.type==="codeIndented"||t.type==="codeText")&&r.push([t.start.offset+e,t.end.offset+e]);return r},"findCodeRanges"),R=l(n=>{let e=null,s=0;return r=>{for(e===null&&(e=$(n));s<e.length&&e[s][1]<=r;)s+=1;return s<e.length&&r>=e[s][0]}},"createIsInCode"),u=l((n,e)=>{let s=e;for(;s<n.length;){const r=n.indexOf(c,s);if(r===-1)return-1;const o=n[r+c.length];if(o===" "||o===`
+`||o==="\r"&&n[r+c.length+1]===`
+`)return r;s=r+c.length}return-1},"findNextMdevalOpening"),S=l(n=>{if(!n.includes(c))return{scriptBlocks:[],markers:[]};const e=R(n),s=[],r=[];let o=0;for(;o<n.length;){const t=n.indexOf(c,o);if(t===-1)break;const i=t+c.length,m=n[i];if(m===`
+`||m==="\r"&&n[i+1]===`
+`){const f=m===`
+`?i+1:i+2,a=n.indexOf(g,f),d=u(n,f),p=d!==-1&&(a===-1||d<a);if(a===-1||p){if(!e(t))throw new Error(p?`mdeval: unclosed script block at offset ${t} (another mdeval opening found before \`-->\`)`:`mdeval: unclosed script block at offset ${t} (missing \`-->\`)`);if(a===-1)break;o=f;continue}const h=a+g.length;e(t)||s.push({content:n.slice(f,a),contentStart:f,start:t,end:h}),o=h;continue}if(m===" "){const f=i+1,a=n.indexOf(g,f);if(a===-1){if(e(t))break;throw new Error(`mdeval: unclosed marker open at offset ${t} (missing \`-->\` on the marker open)`)}const d=a+g.length,p=n.indexOf(E,d),h=u(n,d);if(p===-1||h!==-1&&h<p){if(e(t)){o=d;continue}throw new Error(`mdeval: unclosed marker open at offset ${t} (missing \`<!--/mdeval-->\`)`)}const O=p+E.length;e(t)||r.push({expression:n.slice(f,a),start:t,end:O}),o=O;continue}o=i}return{scriptBlocks:s,markers:r}},"parseMarkdown"),I=l((n,{scriptBlocks:e,markers:s})=>{if(e.length===0&&s.length===0)return!1;const r=[...e.map(t=>[t.start,t.end]),...s.map(t=>[t.start,t.end])].sort((t,i)=>t[0]-i[0]);let o=0;for(const[t,i]of r){if(n.slice(o,t).trim()!=="")return!1;o=i}return n.slice(o).trim()===""},"isOnlyMdeval");export{c as C,b as E,C as M,E as a,_ as b,g as c,I as i,S as p};

package/dist/runtime.mjs

@@ -0,0 +1,4 @@
+#!/usr/bin/env node
+var c=Object.defineProperty;var r=(o,t)=>c(o,"name",{value:t,configurable:!0});import{$}from"zx";const e=r(o=>`
+${String(o)}
+`,"block");export{$,e as block};

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "mdeval",
-  "version": "1.3.1",
+  "version": "1.5.0",
   "description": "Evaluate JavaScript in markdown HTML comments and interpolate results in-place",
   "keywords": [
     "markdown",
@@ -21,6 +21,10 @@
   ],
   "type": "module",
   "bin": "./dist/cli.mjs",
+  "exports": {
+    ".": "./dist/runtime.mjs",
+    "./loader": "./dist/loader.mjs"
+  },
   "imports": {
     "#md-loader": "./dist/md-loader.mjs"
   },
@@ -28,6 +32,7 @@
     "node": ">=20"
   },
   "dependencies": {
+    "@jridgewell/gen-mapping": "^0.3.13",
     "cleye": "^2.3.0",
     "micromark": "^4.0.2",
     "tinyglobby": "^0.2.15",

package/skills/mdeval/SKILL.md

@@ -47,13 +47,42 @@ Duplicate expressions across markers are evaluated once and reused.
 | `Promise` | Auto-awaited, then coerced |
 | `undefined`, `null` | Error |
 
-## Globals
+## Helpers
 
-| Global | Description |
+| Helper | Description |
 |--------|-------------|
 | `block(value)` | Wraps value with newlines for block-level rendering |
 | `$` | [zx](https://google.github.io/zx/) shell — run commands via tagged templates: `` $`git branch` `` |
 
+| File | Access |
+|------|--------|
+| `.md` | Globals — call directly: `block(x)`, `` $`cmd` `` |
+| `.js`, `.ts`, anything else | `import { block, $ } from 'mdeval'` |
+
+CLI (and `--import mdeval/loader`) seeds the helpers on `globalThis` at startup. Modules imported transitively from a `.md` see them too, but in non-`.md` files prefer the explicit import. `import { block, $ } from 'mdeval'` is side-effect-free.
+
+## Importing `.md` exports from a script
+
+Use when a Node script (validation, migration, agent tooling) needs to read exports from a `.md`. Run the script with `--import mdeval/loader`:
+
+```bash
+node --import mdeval/loader ./consumer.js
+```
+
+`consumer.js` can use ordinary static imports against `.md` files:
+
+```js
+import { todos } from './TODOS.md';
+
+console.log(todos);
+```
+
+- `--import mdeval/loader` is a side-effect-only entry — seeds `block`/`$` on `globalThis` and registers the Node ESM loader before any of the script's imports link.
+- Without it, static `import` of a `.md` fails — Node can't resolve `.md` until the loader is registered.
+- The plain `mdeval` import (`import { block, $ } from 'mdeval'`) stays pure — no globals, no loader. Use it when you only want the helpers.
+- Works on `.md` directly too: `node --import mdeval/loader ./TODOS.md`.
+- Runtime stack traces from a `.md` point at original lines and columns automatically.
+
 ## CLI
 
 ```bash
@@ -98,6 +127,15 @@ import { version } from './data.md';
 <!--mdeval version-->1.0.0<!--/mdeval-->
 ````
 
+If the imported `.md` may not yet have mdeval content (stubs filled in over time), use a **namespace import** — named imports against an empty module are rejected by Node's ESM linker, but missing properties on a namespace resolve to `undefined`:
+
+````markdown
+<!--mdeval
+import * as data from './stub.md';
+const version = data.version ?? 'tbd';
+-->
+````
+
 ### Generate Markdown with md-pen
 
 Use [md-pen](https://github.com/privatenumber/md-pen) for formatted output (tables, lists, headings):
@@ -148,7 +186,90 @@ const x = String.fromCharCode(45, 45, 62);
 
 **Place scripts at the top.** Order doesn't affect execution — scripts can appear after the markers that reference them — but top placement signals the file contains generated content.
 
-**Use IIFEs to co-locate logic.** In large docs, keep marker-specific computation inline instead of in a distant script block: `<!--mdeval (() => { ... })()-->`.
+**Markers can span multiple lines — use them to inline logic.** Don't cram expressions into one line. Co-locate marker-specific computation with its output:
+
+````markdown
+<!--mdeval block(table([
+  { name: 'cleye', version: '^2.3.0' },
+  { name: 'md-pen', version: '^0.0.2' },
+]))-->
+| Package | Version |
+| - | - |
+| cleye | ^2.3.0 |
+| md-pen | ^0.0.2 |
+<!--/mdeval-->
+````
+
+For statements or control flow, wrap in an IIFE: `<!--mdeval (() => { ... })()-->`. Reserve script blocks for shared imports or values referenced by multiple markers.
+
+**Standalone markers suppress inline markdown in the value.** When a marker opens a line — standalone paragraph, list item, or blockquote — GitHub treats the entire line as a raw HTML block. Inline markdown in the value (`` `code` ``, `**bold**`, `[link](url)`) is not processed and appears literally.
+
+````markdown
+<!-- ❌ backtick shows literally — line is an HTML block, not inline markdown -->
+<!--mdeval expr-->`value`<!--/mdeval-->
+````
+
+Use a multi-line marker so the value occupies its own lines, which are processed as normal markdown. Use [md-pen](https://github.com/privatenumber/md-pen) to generate formatted values:
+
+````markdown
+<!--mdeval
+import { code, bold, link } from 'md-pen';
+-->
+
+<!--mdeval code('asdf')-->
+`asdf`
+<!--/mdeval-->
+````
+
+Markers inside headings are always inline — markdown in the value always renders there.
+
+**Comments don't work in link URLs or image alt text.** GitHub escapes comment syntax in these positions:
+
+````markdown
+<!-- ❌ comment is URL-encoded as href -->
+[text](<!-- comment -->)
+
+<!-- ❌ comment appears as visible alt text -->
+![<!-- comment -->](image.png)
+````
+
+**`<details>` requires blank lines around the `</summary>` close.** Block-level Markdown inside a `<details>` only renders when blank lines surround the closing `</summary>` tag — otherwise lists, code fences, tables, and other block elements render as literal text. md-pen's `details(summary, content)` emits the correct shape:
+
+````markdown
+<!--mdeval
+import { details, ul } from 'md-pen';
+-->
+
+<!--mdeval block(details(
+  'Click me',
+  ul(['item one', 'item two']),
+))-->
+<details>
+<summary>Click me</summary>
+
+- item one
+- item two
+
+</details>
+<!--/mdeval-->
+````
+
+**Set up a git hook so values never go stale.** Use [Lefthook](https://github.com/evilmartians/lefthook) with this config:
+
+```yaml
+# lefthook.yml
+pre-commit:
+  jobs:
+    - name: mdeval
+      # lefthook's default `gobwas` matcher requires `**` to span 1+ dirs,
+      # so `**/*.md` alone misses root-level files like README.md
+      glob: ["*.md", "**/*.md"]
+      run: |
+        files=$(npx mdeval "**/*.md")
+        [ -n "$files" ] && git add $files
+```
+
+`git add $files` re-stages only the files mdeval actually rewrote. Assumes `.md` paths without spaces.
 
 **Markers in code blocks are safe.** Fenced, indented, and inline code won't be touched — safe to document mdeval syntax in your own README.
 

package/dist/parse-markdown-B18EMsYy.mjs

@@ -1,4 +0,0 @@
-var M=Object.defineProperty;var i=(t,n)=>M(t,"name",{value:n,configurable:!0});import{postprocess as O,parse as u,preprocess as C}from"micromark";const g="mdeval",d=`<!--${g}`,_=`${d} `,E=`<!--/${g}-->`,R=`__${g}_`,p="-->",S=i(t=>{const n=new Map;for(const{expression:s}of t)n.has(s)||n.set(s,n.size);return n},"buildExpressionMap"),k=i(t=>{const n=t.codePointAt(0)===65279?1:0,s=O(u().document().write(C()(t,void 0,!0))),r=[];for(const[o,e]of s)o==="enter"&&(e.type==="codeFenced"||e.type==="codeIndented"||e.type==="codeText")&&r.push([e.start.offset+n,e.end.offset+n]);return r},"findCodeRanges"),I=i(t=>{let n=null,s=0;return r=>{for(n===null&&(n=k(t));s<n.length&&n[s][1]<=r;)s+=1;return s<n.length&&r>=n[s][0]}},"createIsInCode"),T=i(t=>{if(!t.includes(d))return{scriptBlocks:[],markers:[]};const n=I(t),s=[],r=[];let o=0;for(;o<t.length;){const e=t.indexOf(d,o);if(e===-1)break;const c=e+d.length,h=t[c];if(h===`
-`||h==="\r"&&t[c+1]===`
-`){const f=h===`
-`?c+1:c+2,a=t.indexOf(p,f);if(a===-1)break;const l=a+p.length;n(e)||s.push({content:t.slice(f,a),start:e,end:l}),o=l;continue}if(h===" "){const f=c+1,a=t.indexOf(p,f);if(a===-1)break;const l=a+p.length,x=t.indexOf(E,l);if(x===-1){o=l;continue}const m=x+E.length;n(e)||r.push({expression:t.slice(f,a),start:e,end:m}),o=m;continue}o=c}return{scriptBlocks:s,markers:r}},"parseMarkdown"),b=i((t,{scriptBlocks:n,markers:s})=>{if(n.length===0&&s.length===0)return!1;const r=[...n.map(e=>[e.start,e.end]),...s.map(e=>[e.start,e.end])].sort((e,c)=>e[0]-c[0]);let o=0;for(const[e,c]of r){if(t.slice(o,e).trim()!=="")return!1;o=c}return t.slice(o).trim()===""},"isOnlyMdeval");export{d as C,R as E,_ as M,E as a,S as b,p as c,b as i,T as p};