Overview

The StoryKit Network Viewer renders interactive node-and-edge diagrams directly in your post. It is suited to any content where relationships between things matter: family trees, concept maps, dependency graphs, organisational charts, and similar structures.

The viewer is powered by vis.js, a library designed for large, interactive networks. Nodes can be dragged, the whole graph can be panned and zoomed, and the layout is computed automatically from the data you provide.

You define the graph using a simple CSV block placed in the same post. No separate files, no JSON configuration — just rows of comma-separated values written directly in Markdown.

Preview Mode and Expanded Mode

The viewer operates in two modes:

Preview mode (default) shows the graph embedded in the page at a compact size. A set of controls in the caption bar lets the reader open additional information or expand the viewer.

Expanded mode opens when the reader clicks the expand icon in the caption bar. The graph is shown in a larger dialog at full screen width, making it easier to explore complex networks.

Defining Graph Data

Graph data is written as a fenced code block in your post with the id matching the viewer’s dataid attribute (with -csv appended). Each row in the block defines either a node or an edge.

Node rows

1

node, id, label
ColumnDescription
nodeLiteral word node — identifies this row as a node definition
idA unique identifier for this node. Used when defining edges.
labelThe text displayed on the node in the diagram

Edge rows

1

edge, from, to, label
ColumnDescription
edgeLiteral word edge — identifies this row as an edge definition
fromThe id of the node where the edge starts
toThe id of the node where the edge ends
label(optional) Text displayed on the edge itself

Blank lines and lines that do not start with node or edge are ignored, so you can add spacing for readability.

Attributes

Required Attributes

You must provide a dataid attribute (or allow the viewer to locate its data automatically — see Automatic Data Lookup below).

dataid

The identifier used to locate the CSV data block in the page. The viewer looks for an element with an id equal to this value followed by -csv.

1

dataid="my-graph"

If your dataid is my-graph, name your data block my-graph-csv.

Optional Attributes

caption

Text displayed in the caption bar below the viewer. Supports Markdown inline formatting.

1

caption="Relationships between key figures"

aspect

Controls the height of the viewer iframe by setting its CSS aspect-ratio. Expressed as a decimal (width divided by height). Defaults to a wide landscape ratio if omitted.

1
2

aspect="1.5"
aspect="1"

Use aspect="1" for a square viewer, aspect="0.75" for a taller portrait layout.

id

An HTML id applied to the iframe element. Not normally required unless you need to target the viewer with CSS or JavaScript.

1

id="network1"

Automatic Data Lookup

If you omit dataid, the viewer asks the parent page for its own iframe id and then looks for a data element named {id}-csv. This means you can let StoryKit assign the id automatically and name your data block to match.

In practice it is simpler to set dataid explicitly so the relationship between viewer and data is obvious in your Markdown source.

Examples

Simple Example

This example draws a small graph showing three people and the relationships between them.

The data block uses the id people-graph-csv to match dataid="people-graph" on the viewer.

1
2
3
4
5

{% include embed/vis-network.html
    dataid="people-graph"
    caption="A simple relationship graph"
    aspect="1.2"
%}

1
2
3
4
5
6
7
8
9

```
{: #people-graph-csv }
node, alice, Alice
node, bob, Bob
node, carol, Carol
edge, alice, bob, knows
edge, bob, carol, manages
edge, alice, carol, mentors
```

1
2
3
4
5
6
7

{: #people-graph-csv }
node, alice, Alice
node, bob, Bob
node, carol, Carol
edge, alice, bob, knows
edge, bob, carol, manages
edge, alice, carol, mentors

The graph is interactive — nodes can be dragged to rearrange the layout. The viewer computes an initial layout automatically.

Concept Map Example

This example shows a concept map connecting a central idea to related topics.

1
2
3
4
5

{% include embed/vis-network.html
    dataid="concepts"
    caption="Core concepts and their relationships"
    aspect="1"
%}

1
2
3
4
5
6
7
8
9
10
11
12
13
14

```
{: #concepts-csv }
node, core,    Digital Humanities
node, text,    Text Analysis
node, viz,     Visualization
node, data,    Data Curation
node, collab,  Collaboration
edge, core, text,   includes
edge, core, viz,    includes
edge, core, data,   requires
edge, core, collab, enables
edge, text, viz,    informs
edge, data, text,   supports
```

1
2
3
4
5
6
7
8
9
10
11
12

{: #concepts-csv }
node, core,    Digital Humanities
node, text,    Text Analysis
node, viz,     Visualization
node, data,    Data Curation
node, collab,  Collaboration
edge, core, text,   includes
edge, core, viz,    includes
edge, core, data,   requires
edge, core, collab, enables
edge, text, viz,    informs
edge, data, text,   supports

Edge labels describe the nature of each relationship. Extra spaces in the CSV are ignored, so you can align columns for readability.

Data Block Reference

The data block is a standard Markdown fenced code block with a Kramdown id attribute applied to it. The id must follow this naming convention:

1

{dataid}-csv

For example, if dataid="family-tree", the block must be:

1
2
3
4
5

```
{: #family-tree-csv }
node, ...
edge, ...
```

Row Format Summary

Row typeFormatRequired columns
Nodenode, id, labelAll three
Edgeedge, from, toFirst three; label is optional
Edge with labeledge, from, to, labelAll four

Rules

  • Each node id must be unique within the graph.
  • Edge from and to values must match existing node ids.
  • Column order is fixed — do not reorder columns.
  • Leading and trailing whitespace around values is trimmed automatically.
  • Lines that do not start with node or edge are silently ignored.