# drawthe.net, network diagrams as YAML instead of mouse placement

> drawthe.net renders network diagrams from a YAML file, either in a browser editor built on Monaco and Vite or headlessly from the command line. The interesting part for engineers is that placement becomes data, so a diagram can live in version control next to the infrastructure it describes.

**cidrblock/drawthe.net** — drawthe.net draws network diagrams dynamically from a text file describing the placement, layout and icons. Given a yaml file describing the hierarchy of the network and it's connections, a resulting diagram will be created.

- Repository: https://github.com/cidrblock/drawthe.net
- Stars: 1,184 · Forks: 134
- Language: TypeScript
- License: MIT
- Published: 2026-10-19 · Updated: 2026-10-19 · Language: en
- Canonical page: https://hysenlabs.com/projects/cidrblock-drawthe-net

## The complaint is the mouse, not the drawing

The motivation section of the README is unusually blunt about what is wrong with existing tools. Complex network diagrams typically involve placing icons, connections and labels in a tool like Visio or OmniGraffle, using a mouse and constantly zooming in and out for single pixel placement. The stated goal was to be able to describe the diagram in a text file and have it rendered as SVG in the browser, and the author says the real aim was to draw network diagrams as fast as on a dry-erase board without using a mouse.

That framing explains the whole design. The input is a YAML document, the output is SVG, and the intermediate representation is a set of coordinates on a grid. The document has major root sections, and the README names them: diagram for the page the drawing is placed on, title for information about the diagram, icons for objects to be placed, notes for text boxes, connections for lines between objects, and groups for collections of objects.

Because a diagram is a text file, it can be reviewed, diffed and versioned like configuration, which is the appeal for anyone who already runs infrastructure from git. The trade is that a diagram becomes only as good as the coordinate values in the file, and hand-tuning a layout in a text editor is slower than dragging a box for a one-off drawing. The tool wins on repeatability, not on speed for a single picture.

## YAML anchors carry the defaults, so a file stays short

The quick start example in the README shows how the format stays readable. Four anchor blocks define shared attributes, one for icons, one for groups, one for connections and one for notes, and each object then merges the relevant anchor with a merge key:

```yaml
iconDefaults: &iconDefaults
  color: black
  fill: white
  stroke: black
  iconFamily: aws
groupDefaults: &groupDefaults
  fill: "none"
  color: black
  stroke: black
connectionDefaults: &connectionDefaults
  color: "black"
  stroke: "black"
noteDefaults: &noteDefaults
  color: black
  fill: white
  stroke: black
  xAlign: center
  yAlign: center
```

Objects are then written as single lines. An icon needs a family, a specific icon and a position, for example dns: {<<: *iconDefaults, icon: net_route53_hostedzone, x: 2, y: 3 }. Groups list their members, connections list their endpoints, and a group can be a connection endpoint in its own right, which is how a diagram shows a load balancer pointing at a box of servers rather than at each server separately.

Placement is explicit rather than automatic. Icons and notes carry x and y coordinates, with the x and y values given in coordinate steps, plus a w attribute for width in x coordinate steps. The file also supports relative positions, curves between endpoints, line styles, labels on connections, font sizes and text locations, as the examples/ directory shows with files named curves.yaml, line-styles.yaml, labels.yaml, font-sizes.yaml and relative positions.yaml. Nesting groups, custom icons, URL links on objects and mouseover behaviour all have their own example files, and the top-level superspine.yaml sits in the repository root as a worked document.

## The browser editor validates against a JSON Schema

The browser side is a three page application built by Vite. index.html is the YAML editor, which uses Monaco with the YAML language support, JSON Schema diagnostics and a live preview. fullscreen.html is a separate popup window that renders the design shared by the editor through window.opener, and render.html renders a single YAML document with no editor UI, taking either a bundled example through a ?doc= parameter or a saved document through a ?key= parameter.

The diagnostics are the part that makes the editor more than a text area with a preview. The editor validates YAML syntax and the documented diagram properties against a JSON Schema, and its diagnostics panel also reports renderer warnings, including unresolved icons and overlapping groups. So a typo in a property name or a group drawn on top of another one shows up as a problem in the panel rather than as a broken picture.

Strictness is opt-in, which is a sensible design for a format meant to grow. Reusable icon defaults can opt into strict schema validation with type: icon, and unknown properties on the tagged anchor and on icon mappings that inherit it are reported as diagnostics. Untagged custom anchors remain extensible, so you can add your own keys without the editor complaining. The README gives the pattern:

```yaml
cisco: &cisco
  type: icon
  iconFamily: cisco
  icon: router
icons:
  edge: {<<: *cisco, x: 1, y: 1}
```

The renderer itself lives in src/renderer with no browser dependency, and that separation is the reason the same code can produce the same drawing in a headless environment.

## A headless CLI is what makes the tool scriptable

The renderer core has no browser dependency and runs headlessly in Node through src/cli/render.ts, and the README calls that the seam future automation and agent tooling will use. The package.json wires it to a script called render, which is tsx running that file, and the documented usage takes an input YAML path and an output SVG path:

```bash
npm run render -- examples/NTP.yaml out.svg   # headless YAML -> SVG render (Node/CLI)
```

The same renderer is published to npm, so another project can install it as a development dependency and call the binary directly, with width and height options for the output:

```sh
npm install --save-dev drawthe.net
npx drawthe-net diagrams/network.yaml docs/network.svg --width=1200 --height=800
```

The npm package name is drawthe.net while the binary is drawthe-net, and the files list in package.json shows what ships: the bin/ directory, the public/images/ directory holding the icon artwork, and the src/cli/ and src/renderer/ directories.

There is a Hugo integration documented at integrations/hugo/README.md, which inlines SVG generated by the headless CLI from a page-bundle YAML resource, so a blog can carry diagrams without a runtime editor. The repository also holds an mcp/ directory with an mcp script, plus a SKILL.md file, and the README's remark about agent tooling points in that direction.

## Running the editor from a container

Stable GitHub Releases publish versioned images and update the latest tag in GHCR, and the README notes that the package visibility has to be set to Public in the GitHub package settings so Podman can pull the image without authentication. The editor is served with a single command:

```sh
podman pull ghcr.io/cidrblock/drawthe.net:latest
podman run --rm -p 5173:5173 ghcr.io/cidrblock/drawthe.net:latest ui
```

Port 5173 is the one the README gives for the web editor, and the ui argument selects it. The same image converts YAML to SVG without a server at all, and the flags here are worth reading closely because they exist for a reason. The user is set to the invoking user's id and group so the written file is owned by you rather than by root, --userns=keep-id keeps the mapping consistent with that, the working directory is mounted with the :Z relabelling flag for SELinux hosts, and the work directory is set to /workspace so the relative paths in the command resolve inside the container.

```sh
podman run --rm \
  --userns=keep-id \
  --user "$(id -u):$(id -g)" \
  -v "$PWD:/workspace:Z" \
  -w /workspace \
  ghcr.io/cidrblock/drawthe.net:latest \
  diagrams/network.yaml docs/network.svg --width=1200 --height=800
```

The README recommends a versioned tag such as ghcr.io/cidrblock/drawthe.net:v2.0.3 instead of latest, which is the sensible habit when a diagram ends up in a build pipeline.

## Where the approach falls short, and what to use instead

The limits come from the model. Coordinates are supplied, not computed, so there is no automatic layout and no way to ask the tool to fit a diagram to a page. A tool like Graphviz or a layout engine will place nodes for you; drawthe.net will draw exactly where you said, which is what you want for reproducibility and exactly what you do not want when the diagram is a rough sketch.

Icons are the other constraint. The iconFamily and icon values are named from a catalogue, and the editor reports unresolved icons as diagnostics, which means a missing icon surfaces as a warning rather than as a drawn shape. The scripts include an icons:list step that builds the icon families, and the package ships the public/images/ directory, so the bundled artwork covers a fixed catalogue; the project also documents custom icons, so check that mechanism for artwork outside the catalogue.

The comparison to a drawing tool is the obvious one, and the difference in approach is the point of the project. Visio or OmniGraffle give you a canvas and direct manipulation with the mouse. drawthe.net gives you a schema, a diff and a command line, at the cost of manual placement and a constrained visual vocabulary. If you need to sketch a topology once and never touch it again, a canvas tool is faster. If the diagram has to survive code review, live in a repository beside the infrastructure it describes, and be regenerated in CI, this format is the better fit.

For development, the README requires Node.js 20.19+, 22.12+ or 24+, and package.json agrees with an engines field of ^20.19.0 || ^22.12.0 || >=24.0.0. The scripts cover a Vite dev server, a build that typechecks before bundling, eslint, tsc typechecking, a test runner over tests/*.test.ts, and a format step. The project is MIT licensed, and the release history shows three tags on 2026-09-26, v2.0.1, v2.0.2 and v2.0.3, with the npm publish triggered by a non-prerelease GitHub Release.

## Conclusion

drawthe.net suits infrastructure engineers who want a diagram to be a reviewed file rather than a binary attachment, and it suits teams that already keep infrastructure as code, since a diagram and the configuration it depicts can be changed in the same commit. It is the wrong tool if you need a general purpose drawing canvas, because the model is a fixed grid of placed objects and there is no freehand editing, and it is the wrong tool if you need automatic layout, because coordinates are supplied rather than computed. Before adopting it, check that the icon families you need exist, since unresolved icons are reported as editor diagnostics rather than drawn as placeholders, and pin the container image tag, since the README recommends a versioned tag such as ghcr.io/cidrblock/drawthe.net:v2.0.3 rather than latest.

## FAQ

### How do I run the drawthe.net editor locally?

The README requires Node.js 20.19+, 22.12+ or 24+, then npm install and npm run dev to start the Vite dev server. Clear the editor, paste the quick start YAML, and click draw or press ctrl-enter.

### Can drawthe.net produce SVG without a browser?

Yes. The renderer core has no browser dependency and runs headlessly through src/cli/render.ts, so npm run render -- examples/NTP.yaml out.svg works in Node. The npm package installs it as a binary, so npx drawthe-net diagrams/network.yaml docs/network.svg --width=1200 --height=800 renders the same way from another project.

### What does a drawthe.net YAML document contain?

The root sections are diagram, title, icons, notes, connections and groups, plus YAML anchor blocks such as iconDefaults, groupDefaults, connectionDefaults and noteDefaults that objects merge with the << key. Placement is explicit through x and y coordinates in grid steps.

### Does drawthe.net validate my YAML?

Yes. The browser editor checks YAML syntax and documented diagram properties against a JSON Schema, and the diagnostics panel also reports renderer warnings such as unresolved icons and overlapping groups. Strict validation can be opted into for icon defaults with type: icon, while untagged custom anchors stay extensible.

### How do I run drawthe.net in a container?

Pull the image from GHCR and run the ui argument to serve the editor on port 5173, or pass a YAML path and an SVG path to convert a file. The README recommends a versioned tag such as ghcr.io/cidrblock/drawthe.net:v2.0.3 rather than latest.

## Sources

- [cidrblock/drawthe.net on GitHub](https://github.com/cidrblock/drawthe.net)
- [Issues](https://github.com/cidrblock/drawthe.net/issues)
- [License: MIT](https://github.com/cidrblock/drawthe.net/blob/main/LICENSE)
- [README](https://github.com/cidrblock/drawthe.net/blob/main/README.md)
- [Releases](https://github.com/cidrblock/drawthe.net/releases)

---

Hysen Labs editorial analysis, written from the project's own repository and release notes. Cite the canonical page: https://hysenlabs.com/projects/cidrblock-drawthe-net