plotwork sync
Draw the pictures under every diagram fence of Markdown files; --check fails when one is stale. It is a command of the Plotwork command line, the npm package @buun_group/plotwork.
TL;DR
| Question | Answer |
|---|---|
| What does it do? | Draw the pictures under every diagram fence of Markdown files; --check fails when one is stale. |
| How do I run it? | npx -y @buun_group/plotwork@0.1.0-beta.13 sync, or plotwork sync once the package is installed. |
| What does it write? | The Markdown files and their SVGs, unless --check is given. |
| Does it use the network? | No. It reads and writes files on this machine only. |
| 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 sync --help |
Synopsis
plotwork sync <files...> [--check] [--assets <dir>] [--prefix <text>] [--format text|github] [--config <file>]What it does
Draws every diagram fence of the Markdown files as a light and a dark SVG, and writes the picture block under the fence, so the diagram shows on GitHub, GitLab, and any Markdown viewer. A fence whose picture is already current is left as it is.
Each word is a Markdown file, a folder (every .md file under it), or a quoted glob such as "docs/**/*.md". The command expands the glob itself, so it means the same in every shell, and never looks in node_modules, .git, or build output.
With --check it writes nothing and exits 1 when any picture is missing or stale, or any diagram has a mistake. That is the check to run in CI.
Options
| Option | Default | What it does |
|---|---|---|
--check | Off | Write nothing; exit 1 when a picture is missing or stale, or a diagram has a mistake. |
--assets <dir> | assets/diagrams | The folder the SVGs are written to, relative to each Markdown file. |
--prefix <text> | the Markdown file name | The start of each SVG file name and picture id. |
--format text|github | text | github prints each stale fence and each mistake as a GitHub annotation on its line. |
--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
Draw every diagram of the README and the docs folder, and write the pictures.
plotwork sync README.md "docs/**/*.md"Fail when any picture is stale, and write nothing.
plotwork sync --check "docs/**/*.md"The same in a GitHub workflow, with an annotation on each stale fence.
plotwork sync --check --format github "**/*.md"Exit codes
| Code | When |
|---|---|
0 | Every picture is current (with --check), or every picture was written. |
1 | A picture is stale (with --check), or a diagram has a mistake and was not drawn. |
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. |
See also
| Doc | Why |
|---|---|
| Command reference | Every command of the command line |
| Markdown and GitHub | How a fence and its picture block look in a page |
| CI usage | The check in every CI system |
| Exit codes and output formats | What every code and format means |