ProtoML Concepts

ProtoML is not just Markdown with a few extra commands. It behaves more like a small document system for structured protocols, reusable building blocks, and machine-readable exports.

Document shape

A typical ProtoML file combines metadata, structured blocks such as @participants or @tasks, and a freeform @meeting block for the readable narrative.

The structured blocks act as the source of truth. The meeting block is where that structured data is turned into a readable document.

IDs and references

• =lead:Jane Doe,... defines a participant ID
• =0:Release status defines a subject ID
• @@e=lead echoes a known entry into the meeting text
• @@ref=participants:lead:email fetches a specific field

This is what makes ProtoML maintainable: values are defined once and then referenced consistently.

Imports vs. macros

Use @import when you want to reuse content. Use @macro when you want reusable rendering templates.

• Imports help you split large documents into maintainable pieces
• Macros help you standardize repeated render patterns
• They can be combined, but they solve different problems

Tags as shared classification

Tags are ProtoML's reusable classification layer for tasks. Define them locally with @tags, share them with @tags_import, and analyze them with protoparser tags .... Participant lists can be reused in a similar way with @participants_import.

That means ProtoML can support not just writing, but also reporting on work across a document set.

When to use what

• Use metadata for document-level facts
• Use structured blocks when data should be referenceable
• Use @meeting for the human-readable story
• Use @import to split content across files
• Use @macro to standardize repeated rendered patterns
• Use shared tags when multiple files should use the same task vocabulary

Related guides

• Authoring Guide
• Macros Guide
• Reference Map