Getting Started

Install MDZ and write your first skill in under 5 minutes.

Installation

npm install zenmarkdown

Or with your preferred package manager:

pnpm add zenmarkdown
yarn add zenmarkdown

Your First Skill

Create a file named greeting.mdz: 

---
name: greeting
description: When you need to greet someone
---

## Input

$name: $String

## Workflow

1. Generate a friendly greeting for $name
2. Make it appropriately warm
3. Return the greeting

Validate Your Skill

Check for errors before the LLM ever sees it:

mdz check greeting.mdz

This validates syntax, references, and type contracts. Any issues are flagged now—not discovered at runtime with a confused LLM.

Build with Preprocessing (Optional)

If your skill uses macros ({{IF}} constructs) or you want reference inlining, run the build: 

mdz compile greeting.mdz -o ./dist

Preprocessing resolves macros and optionally inlines referenced content. The output is still markdown—just with build-time decisions resolved.

Use Programmatically

import { parse, compile } from 'zenmarkdown';

// Parse to AST
const ast = parse(source);
console.log(ast.frontmatter?.name);

// Validate and extract metadata
const result = compile(source);
if (result.diagnostics.some(d => d.severity === 'error')) {
  console.error('Validation failed:', result.diagnostics);
}

Next Steps