Skip to content

Diagrams that speak YAML

Use the standalone Containerlab viewer in a Zensical documentation site. Write the topology once. Get an interactive diagram, highlighted YAML, and a split view in your documentation. Readers can inspect nodes and download the same file to use in their labs.

The component uses the @containerlab/clab-viewer package. Each diagram runs in its own iframe, keeping its state and styles independent of other diagrams and the documentation theme.

A fence is all it takes

Add a clab fence to a Markdown page:

```clab title="Hello, network" view="split"
name: hello
topology:
  defaults:
    kind: linux
    image: alpine:3.23
  nodes:
    client: {}
    server: {}
  links:
    - endpoints: [client:eth1, server:eth1]
```

And your readers get this:

name: hello
topology:
  defaults:
    kind: linux
    image: alpine:3.23
  nodes:
    client: {}
    server: {}
  links:
    - endpoints: [client:eth1, server:eth1]

Use the actual lab file

For examples that you also run, reference the YAML directly. Paths are relative to the docs/ directory, regardless of which page contains the fence.

```clab file="examples/fabric.clab.yml" annotations="examples/fabric.clab.yml.annotations.json" title="Leaf–spine fabric" height="460"
```

Export an annotations file from the app to preserve a deliberate layout. Without annotations, the viewer arranges the nodes automatically.

Borderless diagrams

Set borderless="true" to place just the canvas between paragraphs. The transparent background blends into the page in either theme. There is no title bar, tab strip, grid, inspector, or toolbar. Readers can still drag to pan and use the mouse wheel or pinch to zoom.

```clab file="examples/fabric.clab.yml" annotations="examples/fabric.clab.yml.annotations.json" title="Leaf–spine fabric" height="360" borderless="true"
```

name: fabric
 
topology:
  defaults:
    kind: nokia_srlinux
    image: ghcr.io/nokia/srlinux:latest
 
  nodes:
    spine1:
      type: ixrd3
    spine2:
      type: ixrd3
    leaf1:
      type: ixrd2
    leaf2:
      type: ixrd2
    leaf3:
      type: ixrd2
    client1:
      kind: linux
      image: ghcr.io/srl-labs/network-multitool:latest
    client2:
      kind: linux
      image: ghcr.io/srl-labs/network-multitool:latest
    client3:
      kind: linux
      image: ghcr.io/srl-labs/network-multitool:latest
 
  links:
    - endpoints: [spine1:e1-1, leaf1:e1-49]
    - endpoints: [spine1:e1-2, leaf2:e1-49]
    - endpoints: [spine1:e1-3, leaf3:e1-49]
    - endpoints: [spine2:e1-1, leaf1:e1-50]
    - endpoints: [spine2:e1-2, leaf2:e1-50]
    - endpoints: [spine2:e1-3, leaf3:e1-50]
    - endpoints: [leaf1:e1-1, client1:eth1]
    - endpoints: [leaf2:e1-1, client2:eth1]
    - endpoints: [leaf3:e1-1, client3:eth1]

The title still names the diagram for assistive technology. Bring back individual controls with options such as toolbar="true" or controls="true"; see customization recipes. In plain HTML, add the boolean borderless attribute to <clab-topology>. Without JavaScript, the source remains readable; a viewer error also reveals the YAML.

Made for reading

  • Topology, YAML, or both. Keyboard accessible tabs with arrow-key navigation.
  • Inspect a node. Click a device or choose it from the node menu. Reveal its source lines with Show in YAML.
  • Take the lab with you. Copy or download the original YAML, including comments.
  • Give the diagram room. Drag to pan, scroll or pinch to zoom, fit the network, or expand the example to full screen.
  • Follow the page theme. Light and dark modes update the mounted graph.
  • Load when needed. Offscreen diagrams and examples starting in YAML view do not load the viewer until needed.

The source remains readable when JavaScript is disabled and is included in print output. Examples are read-only; downloading a topology does not deploy anything.

Continue with the component reference for embedding in another Zensical site or a plain HTML page.