Command line quick start
From an empty page to a diagram that CI keeps in step, in five steps. You need Node 22 or newer and a repository with a Markdown file.
TL;DR
| Question | Answer |
|---|---|
| What do I install? | Nothing. npx fetches the pinned release the first time and keeps it in its cache. |
| What do I write? | A diagram fence in a Markdown file. |
| What draws it? | npx -y @buun_group/plotwork@0.1.0-beta.13 sync README.md, which writes a light and a dark SVG and the picture block under the fence. |
| What do I commit? | The Markdown file and the SVGs it wrote. |
| What fails CI? | sync --check, when the source changed and the picture did not. |
1. Write a diagram
Add a fence to README.md:
```diagramflow "Checkout" direction=downnode shop service "Shop"node pay service "Payments"node db database "Orders DB"shop -> pay : "charge"pay -> db : "record"```The fence is the source. The language is in Writing diagrams, and the Language reference has every statement.
2. Check it
npx -y @buun_group/plotwork@0.1.0-beta.13 validate README.mdA mistake prints its line and column in the file, a code, and a hint that says how to fix it. The command exits 0 when every diagram is valid and 1 when one is not.
3. Draw it
npx -y @buun_group/plotwork@0.1.0-beta.13 sync README.mdsync writes assets/diagrams/checkout.svg and checkout.dark.svg beside the page, named after the diagram's title. It folds the fence into a "Diagram source" block and writes a picture block under it that shows the light or the dark picture to match the reader's theme, with a text description for a screen reader. GitHub, GitLab, and every Markdown viewer show the picture, and the fence stays in the page as the source. Markdown and GitHub shows what the block looks like.
Run sync again after any change to the source. A fence whose picture is already current is left alone.
4. Commit both
git add README.md assets/diagramsgit commit -m "docs: add the checkout flow"5. Check it in CI
Add one step to your pipeline:
npx -y @buun_group/plotwork@0.1.0-beta.13 sync --check README.md "docs/**/*.md"It writes nothing and exits 1 when a picture is missing or older than its source, or a diagram has a mistake, so a pull request that changes a diagram without redrawing it fails. Quote a glob so the command line expands it the same way in every shell. CI usage has the step for GitHub Actions, GitLab CI, Azure Pipelines, Jenkins, and CircleCI.
Next
| To | Run |
|---|---|
| Set defaults, such as the direction of every flow, for the whole repository | Add plotwork.config.json. See Configuration. |
| Draw your Terraform, OpenAPI, or database schema and keep it in step | plotwork generate. See Diagrams as code. |
| Move Mermaid diagrams to Plotwork | plotwork import README.md --write. See Migrating from Mermaid. |
| Change a picture you already have | plotwork read picture.svg > picture.diagram. See Editing an existing diagram. |
See also
| Doc | Why |
|---|---|
| Overview | npx or install, and what each command is for |
| Command reference | Every command, option, and default |
| Troubleshooting | When a step does not do what this page says |