Ecmarkdown

8.1.0 verified Fri May 01 auth: no javascript

A compiler for converting Ecmarkdown algorithm shorthand (a Markdown-inspired syntax used in ECMAScript specifications) into HTML. Current stable version is 8.1.0, with a history of active development. Key differentiators: tailored specifically for writing spec algorithms, supports inline formatting for variables, values, and field references, and integrates with ecmarkup for full spec generation. The library is ESM-only and ships TypeScript type definitions. Release cadence is irregular but frequent, with breaking changes in major versions (e.g., v7 attrs, v6 column numbers, v5 types).

Common errors

error Cannot find module 'ecmarkdown' ↓

cause Missing npm install or incorrect package path.

fix

Run npm install ecmarkdown and ensure the import path is correct.

error SyntaxError: The requested module 'ecmarkdown' does not provide an export named 'parse' ↓

cause Using a CommonJS require or importing from an older version without named exports.

fix

Use ESM import syntax or update to v5+ where named exports are available.

error Property 'id' does not exist on type 'ListItemNode' ↓

cause Migrated to v7.0.0 where ListItemNode.id was replaced by attrs.

fix

Change node.id to node.attrs and handle array of attribute objects.

Warnings

breaking v7.0.0 changed list item 'id' attribute to 'attrs' (array of key-value pairs). ↓

fix Update code that accesses ListItemNode.id to use ListItemNode.attrs instead.

breaking v6.0.0 changed column numbers from 0-based to 1-based in location info. ↓

fix Adjust any logic relying on 0-based column numbers.

breaking v5.0.0 changed parse node types and prevented mixing numbered/bulleted list items. ↓

fix Update type references and ensure lists are homogeneous.

deprecated Default export was removed in v5.0.0; use named exports instead. ↓

fix Replace `import ecmarkdown from 'ecmarkdown'` with `import { parse, emit } from 'ecmarkdown'`.

gotcha Inline formatting constructs (e.g., _ _) are left verbatim if empty; __proto__ is not treated as a variable. ↓

fix Use _ proto _ (with spaces) if you need to denote a variable named 'proto'.

Install

npm install ecmarkdown

yarn add ecmarkdown

pnpm add ecmarkdown

Imports

parse

wrong

const { parse } = require('ecmarkdown')

correct

import { parse } from 'ecmarkdown'

ESM-only since v5; use dynamic import() in CommonJS.

emit

wrong

import { emit } from 'ecmarkdown/emit'

correct

import { emit } from 'ecmarkdown'

Emit is a named export from the main entry point since v5.

FragmentNode

wrong

import { Fragment } from 'ecmarkdown'

correct

import { FragmentNode } from 'ecmarkdown'

Type name changed from Fragment to FragmentNode in v7.1.0.

Quickstart

Shows parsing Ecmarkdown text into an AST and emitting HTML.

import { parse, emit } from 'ecmarkdown';

const input = `1. Let _x_ be *true*.\n  1. ReturnIfAbrupt(_x_).`;
const doc = parse(input);
const html = emit(doc);
console.log(html);
// Expected output: '<emu-alg><ol><li>Let <var>x</var> be <emu-val>true</emu-val>.<ol><li>ReturnIfAbrupt(<var>x</var>).</li></ol></li></ol></emu-alg>'