Command reference

plotwork embed

Print a snippet that shows a picture in a web page or a React app with the viewer @plotwork.official/viewer. It is a command of the Plotwork command line, the npm package @buun_group/plotwork.

TL;DR

Question	Answer
What does it do?	Print a snippet that shows a picture in a web page or a React app with the viewer `@plotwork.official/viewer`.
How do I run it?	`npx -y @buun_group/plotwork@0.8.0 embed`, or `plotwork embed` once the package is installed.
What does it write?	Nothing.
Does it use the network?	No. A link is read by its shape, never fetched, and only the settings file on this machine is read.
Does it read the repository settings?	Yes: the header defaults of the settings file apply to every diagram. See Configuration.
How do I read this in a terminal?	`plotwork embed --help`

Synopsis

plotwork embed <file.svg|file.diagram|link> [--format html|react] [--live] [--pin] [--label <text>] [--config <file>]

What it does

Prints the line that installs the viewer @plotwork.official/viewer and a snippet that shows a picture with it: pan, zoom, tracing a box's lines, and light and dark. html writes the <plotwork-diagram> element for any page, react the <PlotworkDiagram> component.

The target is a Plotwork SVG file, a .diagram or Markdown file (its first diagram is drawn in memory in the auto scheme, as render --scheme auto draws it, and the snippet loads the SVG of the same name), or a hosted link: a published picture https://cdn.plotwork.dev/d/<token>.svg, a stable link /l/<token>.svg, or an organisation embed link /o/<token>.svg. A link is read by its shape and never fetched.

The snippet goes to standard output, and a note for each choice left out goes to standard error: --live is kept only for a stable link or an organisation embed link, and --pin only when the SVG text is on this machine.

Options

Option	Default	What it does
`--format html\|react`	`html`	The snippet to write: `html` for any page, `react` for a React app.
`--live`	Off	Show each new version as it is published, for a stable link or an organisation embed link.
`--pin`	Off	Add the picture's fingerprint, `sha256-` and the SHA-256 of its SVG text, so only exactly that picture is shown. Needs a file, not a link.
`--label <text>`	Off	What the diagram shows, for a screen reader.
`--config <file>`	`PLOTWORK_CONFIG`, else the nearest `plotwork.config.json` or `.plotwork/config.json` from the file up to the repository root	The repository settings file to read: header defaults, and the style rules check applies.

Examples

Show a picture the site serves, in any page.

plotwork embed docs/assets/diagrams/checkout.svg --label "Checkout flow"

Show a stable link in a React app, following each new version.

plotwork embed https://cdn.plotwork.dev/l/<token>.svg --format react --live

Draw a diagram file in memory and pin the snippet to that picture.

plotwork embed checkout.diagram --pin

Exit codes

Code	When
`0`	The snippet was printed, with a note for each choice left out.
`1`	The file is not an SVG, holds no diagram, or the diagram has an error.
`2`	A mistake in the command line: an unknown option, a missing operand, a file or glob that matches nothing, or a settings file that cannot be read. Also when a link is not a hosted Plotwork picture, or `--format` is not `html` or `react`.

Doc	Why
Command reference	Every command of the command line
Your own pages and apps	The viewer, live links, and pinning
Links that always show the latest version	The stable links `--live` follows
Exit codes and output formats	What every code and format means