Run and annotate JS or TS code blocks in MarkDown files!
Note: Version 2 is a bit of a reset for this project as far as how things are implemented. As of runmd@2 CommonJS is no longer supported and and code is expected to use ESM. Also, node@22+ is required.
Install
npm install runmd
Quick Start
Make a copy of your existing README. E.g. cp README.md README_js.md
Edit README_js.md and add the --run flag to any ```javascript blocks you'd like processed
Add // RESULT or console.log() to add runtime state
The context resets when a Setup block is encountered. The Setup block is run as part of setting up the new context.
The context also resets when a Module block is encountered. runmd will run the most recently encountered Setup block, then run the Module block. For example:
globalThis["run" + "md"]; // ⇨ { importMap: { imports: {} } }const foo = 123;// Simple block - we have access to previous block statefoo + 321; // ⇨ 444
runmd;
import "node:path"; // "import" here makes this a Module block
export default {}; //
Setup block context sharing
runmd.importMap
runmd has basic support for import maps in the form of runmd.importMap.imports. For example:
The runmd.onOutputLine callback can be used to transform the generated markdown.
For example:
```javascript --run/** * @param {string} line Output line text. * @param {object|undefined} inBlock Current code block, if this line came from one. * @returns {string|undefined} Return undefined to drop the line, or a string to keep/replace it. */runmd.onOutputLine = (line, inBlock) => { if (line === '```javascript' || line === '```') { return undefined; // Drop code fence lines } if (!inBlock && line.startsWith('# ')) { return line.toUpperCase(); // Rewrite markdown headings } return line;};```