Macros Guide

ProtoML macros provide reusable rendering templates, mainly for HTML-oriented output.

What macros are good for

Macros are best when the same visual or structured output pattern appears repeatedly across documents. They help you standardize presentation without turning your documents into copy-pasted HTML fragments.

Using bundled macros

@macro badge "{{macro_dir}}/badge.pml"
@@macro=badge:text=review

Prefer quotes around paths in CLI usage.

protoparser --listMacros "{{macro_dir}}"
protoparser --macroHelp "{{macro_dir}}/finance/f_entry.pml"

Bundled macro areas

standalone: alert, badge, calendar_event, clicktoreveal, codeblock_copy, image, progress_bar, quote, spoiler, tts, warn_box
grouped sets: actions, decisions, finance, highlight, summary, taskflow, timeline

Writing custom macros

@new_macro
=name:statusPill
=template:
<span class="status-pill status-{{state}}">{{label}}</span>

When writing a macro, keep the input parameters obvious and stable. The best custom macros are easy to understand from the call site alone.

When to prefer imports, macros, or themes

Use imports when the repeated thing is mostly content
Use macros when you need a reusable component with its own structure and presentation, such as alerts, badges, timelines, summaries, or cards
Use themes when the desired effect is document-wide styling such as colors, typography, spacing, or general page chrome
Use tags when the repeated thing is really classification, not rendering

External macro pack workflow

protoparser macro_install init
protoparser macro_install init_registry "./my-registry"
protoparser macro_install init_pack "legal-pack" "./my-registry"
protoparser macro_install add_registry "./my-registry"
protoparser macro_install install "legal-pack"

Use installed packs in a document

@macros_import ".protoml/macro-packs/macros.index.pml"

This is useful when multiple teams or projects should consume the same curated macro set instead of copying files around manually.

Practical advice

Use imports for content reuse and macros for rendering reuse
Prefer themes over macros when you only want to change the overall visual look of the document
Start with bundled macros before creating a shared pack workflow
Treat untrusted macro files as unsafe, especially when they include JavaScript
Keep macro names and parameter names predictable across a macro family