Generating with LLMs / AI Agents

You don’t need a specific AI product to generate ZiraDocs or DocLang — any LLM/agent can emit valid source if it’s given the right system prompt and told how to validate its own output. This is the bring-your-own-model path; the llm-kit/ directory at the repository root has everything you need.

Quick start

1. Pick a system prompt and paste it into your model/agent’s system prompt:
   • llm-kit/system-prompt.md — the main prompt, use this if you have room for it.
   • llm-kit/system-prompt-compact.md — a <8k-character condensed variant, for contexts with a tight system-prompt budget (e.g. some GPT/agent builders).
2. Ask for one of the three real validity targets (see table below) — don’t mix them in one request.
3. Validate the output for real, don’t just trust the model:
   • ZiraDocs: slidelang build --lint-only, or the MCP server’s lint/ get_ast tools.
   • DocLang: doclang build and check for parser errors — there is no linter for DocLang (see the asymmetry below).

The three real validity targets

ZiraDocs and DocLang share one parser/renderer core, but validity works differently across them. There are exactly three combinations worth targeting — never ask a model for a “DocLang strict” syntax, since the parser doesn’t have one:

Target	Structure	AI normalization	Validation tooling
ZiraDocs strict	Rigid SLIDE <type> keyword blocks	Never runs	slidelang build --lint-only, MCP lint/get_ast
ZiraDocs flex	Markdown-like, #/##/---	Always on (via the CLI)	Same as above
DocLang flex	Markdown section hierarchy (#/##/###)	Always on (via the CLI)	doclang build --lint-only, MCP lint/get_ast
DocLang strict	Declared SECTION "Title" blocks with level:/id:	Never runs	Same as above

DocLang’s mode: selects between those last two. Note that DocLang strict is not ZiraDocs strict: it is built from SECTION blocks, and SLIDE does not parse in a .doclang file at all. See DocLang Strict Mode.

The validation asymmetry (read this before trusting “it’s valid”)

ZiraDocs has real, automatable validation: slidelang build --lint-only runs the parser and the full linter (11 rule types producing 40+ distinct diagnostic codes, plus 19 per-layout schemas). The MCP server also exposes lint and get_ast tools that do the same thing programmatically — see llm-kit/validation-checklist.md for the complete, rule-ID-mapped list.

DocLang has none of this. doclang build runs the parser only — no --lint-only equivalent, and the MCP lint/get_ast tools only operate on .slidelang source. For DocLang, “valid” means exactly one thing: the parser produced output without an error-level diagnostic. Be more conservative with DocLang element usage than you might be tempted to be with ZiraDocs, since there’s no automated second opinion catching a mistake.

Two things worth knowing before you start prompting

• Both modes can type a slide’s layout. In flex, a ---\nlayout: <type>\n--- block placed right before a heading sets that slide’s layout; in strict it’s the SLIDE <type> keyword. 23 names are recognized and 19 of them have a schema — for those, the linter validates the slide’s content against it; the other four (chapter, cover, intro, with_directive) type the slide but have no content rules. A name outside the 23 still types the slide and warns. In flex, only layout is read from that block; any other key is reported as having no effect. Note that typing a slide is not yet a visual change — the toolchain ships no CSS for these types (ziradocs/toolchain#254).
• The AI normalizer isn’t a validity crutch. It rewrites loose Markdown-ish flex content into canonical elements, but it never runs in strict mode and won’t invent missing data or fix a chart’s series/column mismatch — get the syntax right, don’t rely on it being repaired.

Go deeper

• llm-kit/README.md — the kit’s own overview and full contents list.
• llm-kit/reference/ — per-target grammar (slidelang-strict.md, slidelang-flex.md, doclang-flex.md), per-element syntax (elements.md), frontmatter fields (frontmatter.md), and deeper worked examples (advanced.md).
• llm-kit/use-case-prompts/ — calibrated skeletons for academic, business-pitch, education, and creative decks.
• llms.txt — the machine-readable entry point (llmstxt.org convention) linking the authoritative docs a model/agent might want to fetch directly.
• examples/gallery/ — the real, lint-clean, dual-format example corpus the kit’s use-case prompts reference instead of duplicating.