Outputs And Rendering

ProtoML treats the source .pml file as structured input that can be rendered in several ways depending on audience and workflow.

Supported outputs

HTML
PDF
JSON
Markdown
Text

These outputs are not just format conversions. They represent different ways of consuming the same structured ProtoML source.

Choosing the right output

HTML: best for rich presentation and macro-heavy output
PDF: best for distribution and archiving
JSON: best for tooling and post-processing
Markdown: best for readable lightweight documentation workflows
Text: best for minimal plain inspection

What each output emphasizes

HTML preserves the richest visual structure and is usually the best default rendering target
PDF is for stable sharing when the final layout should not depend on the reader's environment
JSON exposes the document structure so other tools can inspect or transform it
Markdown and text emphasize readability over interactive or styled output

Typical commands

protoparser "test.pml" html
protoparser "test.pml" pdf
protoparser "test.pml" json
protoparser "test.pml" markdown
protoparser "test.pml" text

Practical output choices

During authoring: HTML or the viewer
For handoff or sign-off: PDF
For integrations or post-processing: JSON
For lightweight text-first review: Markdown or text

Output path behavior

Without an explicit output name, ProtoML derives the output name from the input file
With -output=<name>, you choose the base filename
With a third positional argument, you can target a directory
Files with content imports may auto-render into format-specific subfolders

This automatic path behavior is especially useful once documents start importing HTML or ProtoML snippets, because it avoids cluttering the source directory.

Rendering and macros

Macros are most valuable in HTML output. Markdown and text prioritize readability and intentionally avoid carrying across complex styling or embedded behavior.

Themes and metadata visibility

HTML and PDF output can be influenced either by an explicit CLI theme or by document metadata such as @theme:dark. Metadata output itself can be hidden with -hideMeta or @hide_meta:true when the rendered document should stay visually focused on the body content.

protoparser "test.pml" html -theme=dark
protoparser "test.pml" pdf -hideMeta

Output strategy for teams

Keep one authoritative .pml source
Choose HTML for day-to-day review
Generate PDF only when you need a stable distributable artifact
Use JSON when ProtoML should feed downstream tooling or reporting