mdeval 1.3.1 → 1.4.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
@@ -46,6 +49,69 @@ 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.
+
 ## 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.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "mdeval",
-  "version": "1.3.1",
+  "version": "1.4.0",
   "description": "Evaluate JavaScript in markdown HTML comments and interpolate results in-place",
   "keywords": [
     "markdown",

package/skills/mdeval/SKILL.md

@@ -150,6 +150,37 @@ const x = String.fromCharCode(45, 45, 62);
 
 **Use IIFEs to co-locate logic.** In large docs, keep marker-specific computation inline instead of in a distant script block: `<!--mdeval (() => { ... })()-->`.
 
+**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)
+````
+
 **Markers in code blocks are safe.** Fenced, indented, and inline code won't be touched — safe to document mdeval syntax in your own README.
 
 **Never create a .md file with only a script block and no real content.** Markdown files must contain actual prose/documentation. For shared logic or utilities, create a `.js` or `.ts` file and import it from your markdown instead.