{"id":50708465,"url":"https://github.com/privatenumber/mdeval","last_synced_at":"2026-06-09T13:31:53.419Z","repository":{"id":348594264,"uuid":"1197173253","full_name":"privatenumber/mdeval","owner":"privatenumber","description":"Evaluate JavaScript in Markdown and interpolate results in-place","archived":false,"fork":false,"pushed_at":"2026-05-27T15:06:13.000Z","size":1130,"stargazers_count":55,"open_issues_count":1,"forks_count":0,"subscribers_count":0,"default_branch":"develop","last_synced_at":"2026-05-27T17:07:05.595Z","etag":null,"topics":["cli","dynamic","eval","javascript","markdown","nodejs","readme"],"latest_commit_sha":null,"homepage":null,"language":"TypeScript","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/privatenumber.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":null,"dco":null,"cla":null},"funding":{"github":"privatenumber"}},"created_at":"2026-03-31T11:38:18.000Z","updated_at":"2026-05-27T15:06:38.000Z","dependencies_parsed_at":null,"dependency_job_id":null,"html_url":"https://github.com/privatenumber/mdeval","commit_stats":null,"previous_names":["privatenumber/mdeval"],"tags_count":7,"template":false,"template_full_name":null,"purl":"pkg:github/privatenumber/mdeval","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/privatenumber%2Fmdeval","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/privatenumber%2Fmdeval/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/privatenumber%2Fmdeval/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/privatenumber%2Fmdeval/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/privatenumber","download_url":"https://codeload.github.com/privatenumber/mdeval/tar.gz/refs/heads/develop","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/privatenumber%2Fmdeval/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":34110011,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-05-26T15:22:16.424Z","status":"online","status_checked_at":"2026-06-09T02:00:06.510Z","response_time":63,"last_error":null,"robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":true,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["cli","dynamic","eval","javascript","markdown","nodejs","readme"],"created_at":"2026-06-09T13:31:52.595Z","updated_at":"2026-06-09T13:31:53.408Z","avatar_url":"https://github.com/privatenumber.png","language":"TypeScript","funding_links":["https://github.com/sponsors/privatenumber"],"categories":[],"sub_categories":[],"readme":"\u003cp align=\"center\"\u003e\n\t\u003cimg width=\"160\" src=\".github/logo.webp\"\u003e\n\u003c/p\u003e\n\u003ch1 align=\"center\"\u003emdeval\u003c/h1\u003e\n\nEver wanted dynamic values in your Markdown — package versions, star counts, computed tables — without a separate generation script that's easy to forget about?\n\nmdeval embeds JavaScript directly in your Markdown using HTML comments. The logic lives right next to the content it produces, and the file renders normally everywhere — GitHub, editors, any Markdown viewer — because HTML comments are invisible.\n\nAny 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.\n\n\u003e [!TIP]\n\u003e 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.\n\n## Install\n\n```bash\nnpm i mdeval\n```\n\n## Quick start\n\nmdeval adds two types of HTML comments to your Markdown:\n\nA **script block** is where you write JavaScript. It starts with `\u003c!--mdeval` followed by a newline:\n\n```markdown\n\u003c!--mdeval\nimport fs from 'node:fs/promises';\nconst pkg = JSON.parse(await fs.readFile('package.json', 'utf8'));\n--\u003e\n```\n\nScript blocks support:\n\n- Full Node.js — any built-in module or installed package\n- ESM `import` / `export`\n- Top-level `await`\n- Shell commands via [`$`](https://google.github.io/zx/)\n\nA **value marker** is where the result appears. It starts with `\u003c!--mdeval ` (with a space) followed by a JavaScript expression:\n\n```markdown\nVersion: \u003c!--mdeval pkg.version--\u003e1.0.0\u003c!--/mdeval--\u003e\n```\n\nThe `1.0.0` between `--\u003e` and `\u003c!--/mdeval--\u003e` is the current value — it gets overwritten with the result of `pkg.version` every time you run mdeval:\n\n```bash\nmdeval README.md\n```\n\nThe file is updated in-place. You can pass multiple files or glob patterns: `mdeval README.md \"docs/**/*.md\"`.\n\n`node_modules` and hidden directories are automatically excluded from glob expansion.\n\n## Example\n\n**`CONTACTS.md`** — a contact list stored as data, rendered as a table when viewed:\n\n````markdown\n\u003c!--mdeval\nimport { table, link } from 'md-pen';\n\nexport const contacts = [\n  {\n    name: 'Alice Martin',\n    linkedin: 'https://linkedin.com/in/alice-martin',\n    notes: 'Met at JSConf 2023',\n  },\n  {\n    name: 'Bob Tanaka',\n    linkedin: 'https://linkedin.com/in/bob-tanaka',\n    notes: 'Former colleague at Acme Co.',\n  },\n];\n\nexport const findContact = name =\u003e contacts.find(c =\u003e c.name === name);\n\nconst contactsTable = table(\n  contacts.map(({ name, linkedin, notes }) =\u003e ({ Name: link(linkedin, name), Notes: notes })),\n);\n--\u003e\n\n\u003c!--mdeval block(contactsTable)--\u003e\n| Name | Notes |\n| - | - |\n| [Alice Martin](https://linkedin.com/in/alice-martin) | Met at JSConf 2023 |\n| [Bob Tanaka](https://linkedin.com/in/bob-tanaka) | Former colleague at Acme Co. |\n\u003c!--/mdeval--\u003e\n````\n\n**`TIMELINE.md`** — imports contacts and links them by LinkedIn:\n\n````markdown\n\u003c!--mdeval\nimport { link, ul, bold } from 'md-pen';\n\n// Imports from the mdeval block!\nimport { findContact } from './CONTACTS.md';\n\nconst events = [\n  { date: '2023-10-15', description: 'Attended JSConf 2023' },\n  { date: '2024-03-01', description: `Coffee with ${link(findContact('Alice Martin').linkedin, 'Alice Martin')}` },\n  { date: '2024-11-08', description: 'Started new open-source project' },\n];\n\nconst list = ul(events.map(({ date, description }) =\u003e `${bold(date)} — ${description}`));\n--\u003e\n\n\u003c!--mdeval block(list)--\u003e\n- __2023-10-15__ — Attended JSConf 2023\n- __2024-03-01__ — Coffee with [Alice Martin](https://linkedin.com/in/alice-martin)\n- __2024-11-08__ — Started new open-source project\n\u003c!--/mdeval--\u003e\n````\n\nThe 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.\n\n## Helpers\n\nmdeval ships two helpers used in markers:\n\n| Helper | Description |\n|--------|-------------|\n| `block(value)` | Wraps the value with surrounding newlines so block-level Markdown (headings, lists, tables) renders correctly |\n| `$` | [zx](https://google.github.io/zx/) shell — run commands via tagged templates |\n\nHow you access them depends on the file extension:\n\n| File | Access |\n|------|--------|\n| `.md` | Available as globals — call directly: `block(x)` or `` $`cmd` `` |\n| `.js`, `.ts`, anything else | Import explicitly: `import { block, $ } from 'mdeval'` |\n\nThe `.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.\n\n## Using `.md` exports from a script\n\n`.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.\n\nRun your script with `--import mdeval/loader`:\n\n```bash\nnode --import mdeval/loader ./consumer.js\n```\n\n`consumer.js` can then use ordinary static imports against `.md` files:\n\n```js\nimport { todos } from './TODOS.md'\n\nconsole.log(todos)\n```\n\n`--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.\n\nThe 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\".\n\nYou can also point `--import mdeval/loader` at a `.md` file directly:\n\n```bash\nnode --import mdeval/loader ./TODOS.md\n```\n\nRuntime stack traces from a `.md` point at original lines and columns — the loader sets up source maps automatically.\n\n## Notes\n\n- 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.\n\n- **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:\n\n  ```markdown\n  \u003c!--mdeval block(table([\n    { name: 'cleye', version: '^2.3.0' },\n    { name: 'md-pen', version: '^0.0.2' },\n  ]))--\u003e\n  | Package | Version |\n  | - | - |\n  | cleye | ^2.3.0 |\n  | md-pen | ^0.0.2 |\n  \u003c!--/mdeval--\u003e\n  ```\n\n  When the expression needs statements or control flow, wrap it in an IIFE:\n\n  ```markdown\n  \u003c!--mdeval (() =\u003e {\n    const n = 3;\n    if (n % 2 === 0) { return 'even' }\n    return 'odd'\n  })()--\u003eodd\u003c!--/mdeval--\u003e\n  ```\n\n  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.\n\n- Marker expressions are **auto-awaited** — promises resolve automatically. Async APIs work directly in a marker without a script block:\n\n  ```markdown\n  Status: \u003c!--mdeval (await fetch('https://api.github.com/repos/privatenumber/mdeval')).status--\u003e200\u003c!--/mdeval--\u003e\n  ```\n\n- You can **import from other `.md` files**. Only the script blocks are executed — no markers are processed:\n\n  ```markdown\n  \u003c!--mdeval\n  import { version } from './data.md';\n  --\u003e\n  ```\n\n  This lets you share constants and logic across multiple markdown files.\n\n  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:\n\n  ```markdown\n  \u003c!--mdeval\n  import * as data from './stub.md';\n  const version = data.version ?? 'tbd';\n  --\u003e\n  ```\n\n- 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()`.\n\n## Caveats\n\n- Script code **cannot contain `--\u003e`** — it closes the HTML comment. Rewrite `x-- \u003e y` as `x -= 1; x \u003e y`.\n- Scripts are **JavaScript only** — no TypeScript.\n- Values **cannot contain `\u003c!--mdeval `** or **`\u003c!--/mdeval--\u003e`** — mdeval will throw to prevent document corruption.\n\n## Tip: md-pen\n\n[md-pen](https://github.com/privatenumber/md-pen) provides typed utilities for generating tables, lists, and other Markdown structures — useful when markers need to produce formatted output:\n\n```markdown\n\u003c!--mdeval\nimport { table, bold, link } from 'md-pen';\nconst deps = [\n  ['cleye', '^2.3.0'],\n  ['md-pen', '^0.0.2'],\n];\nconst depsTable = table(deps.map(([name, version]) =\u003e [\n  link(`https://npm.im/${name}`, bold(name)),\n  version,\n]));\n--\u003e\n\n\u003c!--mdeval block(depsTable)--\u003e\n| Package | Version |\n| - | - |\n| [__cleye__](https://npm.im/cleye) | ^2.3.0 |\n| [__md-pen__](https://npm.im/md-pen) | ^0.0.2 |\n\u003c!--/mdeval--\u003e\n```\n\n## Git hook\n\nRun mdeval automatically before every commit so values never go stale. [Lefthook](https://github.com/evilmartians/lefthook) makes this easy:\n\n```sh\nnpm install lefthook --save-dev\n```\n\n```yaml\n# lefthook.yml\npre-commit:\n  jobs:\n    - name: mdeval\n      # lefthook's default `gobwas` matcher requires `**` to span 1+ dirs,\n      # so `**/*.md` alone misses root-level files like README.md\n      glob: [\"*.md\", \"**/*.md\"]\n      run: |\n        files=$(npx mdeval \"**/*.md\")\n        [ -z \"$files\" ] || git add $files\n```\n\n`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.\n\n## Agent Skills\n\nThis 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.\n\n## Related\n\n- [comment-mark](https://github.com/privatenumber/comment-mark) — Same idea of using HTML comment placeholders, but you write the script externally and pass values in via a JavaScript API. Useful when you want to keep the logic separate from the Markdown.\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fprivatenumber%2Fmdeval","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fprivatenumber%2Fmdeval","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fprivatenumber%2Fmdeval/lists"}