# Graphs

Since a Zettelkasten is a collection of notes and the links between said notes, the perfect representation is a directed graph. Graphs help a lot in understanding your Zettelkasten, to give you a quick and intuitive overview of everything that is going on.

`settle` provides the `--graph` option for the `query` command, which turns the query results into a format of your choice. There are currently three available formats, namely:

- an interactive visualisation for the web-browser, whose code is printed when the `--graph` option is given `vizk` as a value (check the link for usage instructions)
- DOT (.gv), obtained by passing `dot` as the value to the `--graph` option. This format is used by many graph renderers, such as `xdot` or `graphviz` (and its many sub-tools).
- providing `json` as a value to the `--graph` option returns the query results as a JSON object with several properties.

## Visualising a DOT graph

You may use, for example, `xdot` to explore the DOT graph interactively:

    $ settle query --graph dot >zk.gv
    $ xdot zk.gv

Or, you may create a JPG image using `circo` ([on Arch Linux,] comes with the `graphivz` package):

    $ settle query --graph >zk.gv
    $ circo -Tjpg zk.gv >graph.jpg

## JSON format specification

There are four properties in total: - `nodes`: an array containing all the notes' titles - `edges`: an array of arrays where the first element [in the sub-array] is the index of the source Zettel [in the `nodes` array], the second is the index of the target Zettel, and the third is the weight of the link (which is `""` (empty string) if the target Zettel exists, and `"ghost"` if it doesn't) - `node_holes`: always empty array (`[]`) - `edge_property`: always `"directed"`

A minimal example of the format is this:

    {
        "nodes": [
            "My first super interesting note",
            "My second, albeit less interesting note",
            "My third note, which is unrelated"
        ],
        "node_holes": [],
        "edge_property": "directed",
        "edges": [
            [
                0,
                1,
                ""
            ]
        ]
    }

This minimal example describes a Zettelkasten where `My first super interesting note` (indexed with `0`) links to `My second, albeit less interesting note` (indexed with `1`), and how `My third note, which is unrelated` has no links to or from it. The edge weight `""` (empty string) implies that the target exists in the Zettelkasten.