# plotwork embed

> Page: https://docs.plotwork.dev/cli/commands/embed. Index of every page: https://docs.plotwork.dev/llms.txt

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](https://docs.plotwork.dev/cli/configuration.md). |
| How do I read this in a terminal? | `plotwork embed --help` |

## Synopsis

```sh
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.

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

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

```sh
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.

```sh
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`. |

## See also

| Doc | Why |
|---|---|
| [Command reference](https://docs.plotwork.dev/cli/commands.md) | Every command of the command line |
| [Your own pages and apps](https://docs.plotwork.dev/hosted-diagrams.md#your-own-pages-and-apps) | The viewer, live links, and pinning |
| [Links that always show the latest version](https://docs.plotwork.dev/hosted-diagrams.md#8-links-that-always-show-the-latest-version) | The stable links `--live` follows |
| [Exit codes and output formats](https://docs.plotwork.dev/cli/exit-codes-and-output.md) | What every code and format means |