Reuse And Imports Guide

ProtoML has several reuse mechanisms, and they solve different problems. This guide connects them into one practical workflow so you can choose the right one quickly.

Choose the right reuse tool

@import name "file" pml|html when you want to inject maintained content into the meeting output
@participants_import "file.pml" when multiple documents should share the same participant roster
@tags_import "file.pml" when multiple documents should share the same task vocabulary
@macros_import "file.pml" when one generated or curated macro index should expose many macros at once
@macro name "file.pml" when a document should register one concrete macro file directly

Shared participants

@participants_import "_participants.pml"

@tasks
-[ ] Prepare release notes @ptp=lead

@meeting "Minutes"
Lead: @@e=lead
Lead mail: @@ref=participants:lead:email

Use this when teams, committees, or recurring meeting series keep reusing the same people. The participant file becomes the shared source of truth.

Shared tags

@tags_import "_workflow_tags.pml"

@tasks
-[ ] Check deployment window @tag=review
-[ ] Confirm fix plan @tag=blocked

Use shared tags when reporting and workflow consistency matter across many documents. This is the most common cross-file reuse mechanism after plain imports.

Content imports

@import appendix "appendix.pml" pml
@import legal "legal_notice.html" html

@meeting "Minutes"
## Appendix
@@output=appendix
## Notice
@@import=legal

Content imports are best for maintained snippets, appendices, reusable sections, or legal text that should live outside the main document.

Direct macros vs. macro indexes

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

This direct form is best for a small number of known macros inside one document or repository.

@macros_import ".protoml/macro-packs/macros.index.pml"
@@macro=decisionCard:title=Storage;text=Use the replicated tier

This indexed form is best once you install packs through macro_install and want one shared entry point for many macros.

Recommended file layout

meetings/
  weekly-sync.pml
shared/
  _participants.pml
  _workflow_tags.pml
snippets/
  appendix.pml
  legal_notice.html

This layout keeps shared assets explicit and avoids mixing long-lived vocabularies with one-off meeting text.

Common mistakes

Using a macro when the repeated thing is really just maintained content
Keeping participant lists local in every meeting even though the same roster repeats weekly
Using local tags everywhere and then wondering why cross-file statistics are inconsistent
Registering many macros one by one when a generated @macros_import index would be cleaner

Rule of thumb

Reuse data with imports to blocks such as participants and tags
Reuse content with @import
Reuse rendering with macros