\n\nWrite once in readable **AzeMark**, publish everywhere: deterministic,\nself-contained **HTML**, **SVG**, **PNG**, and **PDF** from a single Source —\nno build chain, no runtime dependencies in your output.\n\n- **Deterministic.** The same Source always produces byte-identical\n Artifacts. Every Artifact carries the content hash of the Document it\n represents, so you can prove what you published.\n- **Self-contained.** Fonts are embedded, scripts are never emitted, and\n Artifacts phone home to nothing. Send the file; it renders as-is.\n- **Fail-closed.** Invalid Sources produce precise, ranged diagnostics —\n never a half-written Artifact, never a stack trace.\n- **Offline math.** Equations render through a pinned, sandboxed KaTeX\n bundle. Readable aliases cover Greek, fractions, sums, integrals, limits,\n matrices, and more; raw LaTeX stays denied unless you explicitly opt in.\n- **Diagrams included.** Mermaid flowcharts, GFM-style tables, and callouts\n are first-class Blocks rendered through a pinned browser engine.\n\n## AzeForge currently covers these broad rendering categories:\n\n| Category | Representative native plugins |\n| --- | --- |\n| Mathematics | `equation`, `derivation` |\n| Visualization | `plot`, `chart` |\n| Geometry | `geometry` |\n| Chemistry | `formula`, `reaction`, `structure` |\n| Electrical engineering | `circuit` |\n| Digital timing | `timing` |\n| Diagrams | `diagram`, `mermaid` |\n| Engineering diagrams | `control`, `free-body` |\n| Software and data models | `sequence`, `state`, `entity`, `class` |\n| Structured technical content | `table`, `algorithm`, `statement`, `example` |\n| Document composition | `figure`, `bibliography`, `callout` |\n\nSee the [native plugin family tree](docs/native-plugin-family-tree.md) for the\nfull catalog and family relationships.\n\n## Install\n\n```bash\nnpm install -g @aruzone/aze-forge\nazeforge --help\n```\n\nRequires Node.js 22 or 24 on Ubuntu or macOS (Windows support is parked).\nThe install fetches a pinned browser engine for diagrams and visual formats;\non npm 11+ allow its install script once:\n\n```bash\nnpm install -g @aruzone/aze-forge --allow-scripts=puppeteer\n```\n\nDetails, offline installs, and uninstall live in\n[docs/development.md](docs/development.md#browser-engine-and-offline-installs).\n\n## Try it: your first document\n\nCreate a Source file — plain Markdown with a small front matter header:\n\n```bash\ncat > hello.aze.md <<'EOF'\n---\nazemark: 2\ntitle: Hello AzeForge\nauthor:\n - Test Author\ntheme: default\n---\n\n# Introduction\n\nThis document tests the current compiler.\nEOF\n```\n\nValidate it (silence means valid) and render it:\n\n```bash\nazeforge validate hello.aze.md && echo VALID\nazeforge render hello.aze.md --output hello.html && open hello.html\n```\n\n## Try it: equations\n\nReadable math — no LaTeX required:\n\n```bash\ncat > equation.aze.md <<'EOF'\n---\nazemark: 2\ntitle: Equation check\n---\n\n:::: equation\nid: euler\n----\nF(omega) = integral x=0..infinity of x^2 dx\n::::\nEOF\n\nazeforge render equation.aze.md --output equation.html\n```\n\nNeed raw LaTeX? It is denied by default and opt-in per command:\n\n```bash\nazeforge validate equation.aze.md --allow-raw-latex && echo ALLOWED\n```\n\n## Try it: tables and callouts\n\n```bash\ncat > blocks.aze.md <<'EOF'\n---\nazemark: 2\ntitle: Blocks\n---\n\n:::: callout\nvariant: note\ntitle: Determinism note\n----\nCallout bodies parse ordinary Markdown, including nested equations.\n::::\n\n:::: table\ncaption: Thermal properties\nid: materials\n----\ncolumns:\n - key: material\n name: Material\n - key: density\n name: Density [kg/m^3]\n type: quantity\n unit: kg/m^3\n - key: conductivity\n name: Conductivity [W/(m K)]\n type: quantity\n unit: W/(m K)\nrows:\n - material: Aluminum\n density: 2700\n conductivity: 205\n - material: Steel\n density: 7850\n conductivity: 50\n::::\nEOF\n\nazeforge render blocks.aze.md --output blocks.html\n```\n\n## Try it: diagrams\n\nMermaid flowcharts render through the pinned browser engine:\n\n```bash\ncat > diagram.aze.md <<'EOF'\n---\nazemark: 2\ntitle: Diagram\n---\n\n:::: mermaid\nid: flow\ntitle: Measurement flow\n----\nflowchart LR\n start[Start] --> inspect[Inspect setup]\n inspect --> done[Done]\n::::\nEOF\n\nazeforge render diagram.aze.md --output diagram.html\n```\n\n## Try it: every format and theme\n\nOne Source, four Artifacts, three themes (`default`, `academic`,\n`dark-presentation`):\n\n```bash\nfor format in html svg png pdf; do\n azeforge render hello.aze.md --output \"hello.${format}\"\ndone\nazeforge render hello.aze.md --output hello-academic.html --theme academic\n```\n\nArtifacts embed their fonts and contain no scripts:\n\n```bash\ngrep -o 'data:font/woff2;base64' hello.html | sort -u\ngrep -i ' invalid.aze.md\nprintf 'previous Artifact' > preserved.html\nazeforge render invalid.aze.md --output preserved.html; echo \"exit: $?\"\ncat preserved.html\n```\n\n## Try it: ask what the language accepts\n\n`azeforge grammar` publishes every registered directive as data — header keys,\nbody records, field vocabularies, ceilings — derived from the same tables the\nvalidators use, so it cannot drift from what compiles:\n\n```bash\nazeforge grammar --json | jq '.directives | length'\n# 25\nazeforge grammar --json --directive plot | jq -c '.directives[0].header.fields | map(.key)'\n# [\"id\",\"number\",\"width\",\"height\",\"legend\",\"grid\",\"parameters\",\"x-axis\",\"y-axis\"]\nazeforge grammar --json --directive plot | jq -c '[.directives[0].body.records[].kind]'\n# [\"function\",\"line\",\"scatter\"]\nazeforge version --json | jq -c '.schemas[] | select(.id==\"azeforge.grammar/v1\")'\n# {\"id\":\"azeforge.grammar/v1\",\"version\":1}\n```\n\n`--directive ` narrows the report to one directive and an unknown type\nexits `2`; without `--json` the human report goes to stderr and stdout stays\nempty. The JSON document validates against the packaged\n`schemas/grammar.json`.\n\n## Try it: live rebuild and preview\n\nRecompile on every save, or preview in a loopback browser tab:\n\n```bash\nazeforge watch hello.aze.md --output hello.html\nazeforge serve hello.aze.md --port 0\n# serve: listening on http://127.0.0.1:62545/ for hello.aze.md\n```\n\n`watch` preserves the last successful Artifact through failed cycles; `serve`\nbinds loopback only and never shows stale content. Stop either with\n`SIGINT` or `SIGTERM`.\n\n## Try it: prove determinism\n\nRender twice; the bytes — and their hashes — must match exactly:\n\n```bash\nazeforge render hello.aze.md --output hello-first.html\nazeforge render hello.aze.md --output hello.html\ncmp hello-first.html hello.html && echo IDENTICAL\nshasum -a 256 hello-first.html hello.html\n```\n\n## Commands\n\n| Command | Purpose |\n| -------------- | ---------------------------------------------------- |\n| `render` | Compile a Source to `html`, `svg`, `png`, or `pdf` |\n| `validate` | Check a Source; silent success, ranged diagnostics |\n| `format` | Canonical LF/UTF-8 formatting (`--write`, `--check`) |\n| `watch` | Recompile on save, preserving last good Artifact |\n| `serve` | Loopback live preview with reload |\n| `capabilities` | Supported commands, formats, engines (`--probe`) |\n| `grammar` | Machine-readable AzeMark 2 directive grammar |\n| `version` | Tool, runtime, and schema versions (`--json`) |\n\nExit statuses: `0` success (including warning-only validation), `1` the\noperation was accepted but the Source failed, `2` the invocation itself was\nmalformed. Run `azeforge --help` for full options.\n\n## Library\n\nThe published package exposes exactly three supported entry points; only\ndocumented exports are supported, and implementation helpers are not\nreachable through the package (deep imports resolve to nothing):\n\n| Entry point | Responsibility |\n| --- | --- |\n| `@aruzone/aze-forge` | `createCompiler`, high-level compiler operations, and `buildGrammarDocument` |\n| `@aruzone/aze-forge/contracts` | Public types, JSON schemas and schema identifiers, without Node-only imports or engine initialization |\n| `@aruzone/aze-forge/adapters` | Trusted registry/adapter contracts and the root-confined filesystem asset adapter |\n\n```js\nimport { createCompiler, buildGrammarDocument } from \"@aruzone/aze-forge\";\nimport { createVersionReport, GRAMMAR_SCHEMA_ID } from \"@aruzone/aze-forge/contracts\";\nimport { getBuiltInRegistry } from \"@aruzone/aze-forge/adapters\";\n```\n\nThe runtime compiler is Node-oriented; a browser-safe `contracts` entry\ndoes not promise browser compilation. Breaking library changes during\n`0.x` require a minor-version increment; AzeForge Web pins the exact\npublished version.\n\n## Uninstall\n\n```bash\nnpm uninstall -g @aruzone/aze-forge\nrm -rf ~/.cache/puppeteer # optional: remove the downloaded browser engine\n```\n\n## Contribute\n\nDevelopment setup, the test seams, the acceptance runner, and the release\nprocess are in [docs/development.md](docs/development.md). AzeForge is\n[MIT](LICENSE)-licensed.\n","readmeFilename":"README.md"}
![\"AzeForge\"](\"docs/assets/azeforge-logo-03-2.jpg\"){kind=logo}
\n