Woodcut

Woodcut draws the diagrams in my writing. I describe a figure as data, and a small web component draws it. Every figure sits in the same frame, so a reader learns its controls once.

Why it exists

A diagram should not need its own manual. If each post draws its figures a new way, the reader has to learn a new way to read each one. I wanted to settle that once. In my own words: "Woodcut to create reusable artefacts, designs so I don't need to explain things again and again."

So the rules for figures live in one written rulebook, and the code follows them. The rulebook puts the idea in one line: "Repetition is the system: the same primitives, post after post."

Data in, figure out

A figure starts as a small JSON file. In a post, I name that file in a figure block. The site picks the matching Woodcut element, and the element draws the figure as SVG in the reader's browser. The components have no dependencies.

There are five diagram types, and each one answers one question. A block diagram shows where. A flowchart shows which way. A swimlane shows who. A state machine shows what can happen. A sequence shows in what order. Flowcharts and swimlanes reuse the block diagram's drawing code, so the five types need only three shapes of data.

One set of controls

The frame gives every type the same four controls. A part of a figure can carry a short note that shows on hover. Expand opens the figure full screen, where the reader can zoom from 10% to 600% and drag to look around. A figure with more than one view gets a menu to switch views. A figure with steps gets a numbered dial and a play button.

The author decides which of these a figure needs, through the data it holds. A reader who asks for less motion sees a stepped figure without the animation.

The components take their colours and fonts from a small set of style variables. Woodcut ships defaults, and a site can set its own. This site sets them to its paper and ink.

From a merge to a reader

Woodcut is public, under the MIT licence. When a change with a new version number merges, a release job publishes the package to npm and tags the release. This site installs a release I choose, and serves it to each post page.

Two of my other projects, Loom and Atlas, still carry copies of the first release, 0.1.0. Atlas uses one copy for a diagram in a view that runs only on my machine, and bundles another into a design document.

Where it goes next

The plan is to package Woodcut for the tools that write my design documents, so those documents use the same figures as my posts. Whether the code moves into Atlas for that is still open. A plugin that wraps it waits until someone asks for one.

A public catalog shows each diagram type working, at arjunkhera.github.io/woodcut/docs.