Publish diagrams

Keep .flowmark as the source of truth, then choose delivery based on where the diagram will be read. Most destinations should receive static SVG; use a live host only when interaction changes the reader’s experience.

Author once, deliver deliberately

The hosted Studio, local CLI Studio, and VS Code extension all edit the same source language and use the same diagnostics, formatter, layout, and renderer. Publishing does not require choosing a different authoring format:

1. Create or open a .flowmark file in Studio or your editor.
2. Commit the source when the diagram belongs to a repository.
3. Choose a static or live delivery path from the table below.
4. Add CLI validation in CI when generated output must stay synchronized.

Fenced Markdown can remain inside its Markdown document. Standalone files work especially well when the same diagram is imported by an application, rendered in CI, and reopened in Studio.

Choose by destination

Destination	Recommended path	Package
README, wiki, pull request, slide	Portable SVG	@ministryplace/flowmark-cli
Static or server-rendered site	Build-time SVG	@ministryplace/flowmark
Astro, MDX, or Unified site	Flowmark fences	@ministryplace/flowmark-remark
Markdown-it or VitePress site	Flowmark fences	@ministryplace/flowmark-markdown-it
Vite or another supported bundler	Flowmark imports	@ministryplace/flowmark-unplugin
Framework-agnostic web app	Web component	@ministryplace/flowmark-element
React app or editable teaching UI	React	@ministryplace/flowmark-ui
Validation and generated artifacts	CI	@ministryplace/flowmark-cli

Static is the default for a reason

A static SVG loads with the page, works without JavaScript, can be cached, and survives outside your application. It is also easier to secure. CLI output carries its theme by default; set snapshotTheme: true when producing the same portable file through the JavaScript SDK.

Use an interactive host when at least one of these is true:

• readers need to pan or zoom a dense diagram
• the source changes at runtime
• the diagram follows the host application’s theme
• an authored story needs playback controls
• the diagram is itself an editor or teaching surface

Do not ship an editor and layout engine to the browser merely to display an image.

The public package boundary

For normal applications, choose the package that owns your destination:

• @ministryplace/flowmark — JavaScript SDK and rendering facade
• @ministryplace/flowmark-cli — files, validation, and automation
• @ministryplace/flowmark-element — <flowmark-diagram> for any browser framework
• @ministryplace/flowmark-ui — React live view, playground, static helper, and highlighting
• @ministryplace/flowmark-remark — static Flowmark fences for Remark and Unified hosts
• @ministryplace/flowmark-markdown-it — static Flowmark fences for Markdown-it hosts
• @ministryplace/flowmark-unplugin — standalone .flowmark imports for build-tool hosts

Lower-level packages expose pipeline seams for advanced tooling. They are not required for ordinary embedding.

@ministryplace/flowmark-build is shared adapter infrastructure. Applications normally consume it indirectly through the Markdown or Unplugin packages.

Decide who owns the source

• Repository-owned: commit .flowmark beside generated .svg; rebuild in CI.
• Application-owned: keep the source in code or data and render through the SDK.
• Reader-owned: use FlowmarkPlayground only when editing is part of the feature.

This ownership decision matters more than framework choice. It determines how diagrams are reviewed, validated, cached, and updated.