Use it in VS Code

The idocs extension for VS Code makes a diagram as quick to write as it is to read. It highlights the YAML, checks it as you type, completes node ids and icon names, and shows the diagram next to the file, updating on every keystroke.

Install it

Marketplace

Open the Extensions view, search for idocs (publisher thepackagelabs) and install it. Or from a terminal:

code --install-extension thepackagelabs.idocs-vscode

From a .vsix

Every release attaches the extension as a .vsix file on GitHub. Download it and run:

code --install-extension idocs-vscode-0.2.0.vsix

Open any project that has a diagrams/<name>/diagram.yaml. The extension activates by itself.

The live preview

Open a diagram and press Ctrl+K V (⌘+K V on a Mac), or click the preview button in the editor’s title bar.

• It follows your typing. The preview is built from the text in the editor, saved or not. A setting makes it wait for a save instead.
• It survives mistakes. While the text has an error, the preview keeps the last diagram that worked and lists the problems above it. Click a problem to jump to it.
• It follows your cursor. The node you are editing is outlined in the diagram. Click a node in the diagram and the editor jumps to where it is written.
• It follows you to another diagram when you switch files. The padlock keeps it where it is.
• It is the real thing. Pan, zoom, open a node’s details, switch views and play scenarios as packets, a sequence diagram or a swimlane story. It takes your editor’s colours and fonts, light or dark.
• It looks inside. A node with a diagram: has Expand and Open in the preview too, and the diagrams it holds follow your edits to them. See nested diagrams.

Writing

Problems are the checks idocs check runs, shown in the Problems panel as you type: unknown keys with a suggestion, edges to nodes that do not exist, steps with no route, icons that do not resolve, refs: that point at files that have since moved, and nodes that open a diagram that is missing or that leads back to itself.

Completion knows where you are. In a node it offers the node’s keys with their documentation; after kind: it offers the kinds; at the start of an edge or a step it offers your node ids, and after -> the other end; after diagram: it offers the other diagrams of the project.

edges:
  - web -> |        # offers: api, db, ...
nodes:
  api:
    icon: postgre|  # offers: postgresql, ...

Navigation works on ids. Go to the definition of a node from an edge or a scenario, find every use of it, or rename it: every edge, step, lane and view in diagram.yaml and in the scenario files changes together, and so does the node’s nodes/<id>.md.

Hover a node for its connections, an icon to see it, a key for what it means. The outline lists nodes, edges, views and the steps of each scenario. The status bar shows the state of the diagram you are editing; click it to see the problems. Help → Welcome → Get started with idocs walks through all of this.

Command
idocs: Open Preview to the Side	Preview the diagram you are editing
idocs: New Diagram	Create diagrams/<name>/ with a working diagram, the same files as idocs new
idocs: Insert Icon	Search the icon catalog and insert a name
idocs: Check All Diagrams	Compile every diagram in the workspace

Settings

Setting	Default
idocs.diagnostics.enable	true	Show errors and warnings in the Problems panel
idocs.updateDelay	250	Milliseconds to wait after typing before checking and updating the preview
idocs.preview.refreshOn	type	type updates from unsaved text, save waits for a save
idocs.preview.followCursor	true	Outline the node under the cursor in the preview

Note

The extension carries the compiler of its own release. If your project uses a newer idocs than the extension, a key that was added since may be reported as unknown until the extension is updated. idocs check always uses the version installed in your project.

Diagram files are recognised by their place: diagrams/<name>/diagram.yaml and diagrams/<name>/scenarios/*.yaml. For a diagram kept somewhere else, point the language at it with VS Code’s files.associations setting. The folder still needs a diagram.yaml.