jekyll-graph

Add d3 graph generation to jekyll.


Keywords
d3, graph, hierarchy, jekyll, network, tree, web
License
GPL-3.0
Install
gem install jekyll-graph -v 0.0.6

Documentation

Jekyll-Graph

⚠️ This is gem is under active development! ⚠️

⚠️ Expect breaking changes and surprises until otherwise noted (likely by v0.1.0 or v1.0.0). ⚠️

Jekyll-Graph generates data and renders a graph that allows visitors to navigate a jekyll site by clicking nodes in the graph. Nodes are generated from the site's markdown files. Links for the tree graph are generated from jekyll-namespaces and links for the net-web graph from jekyll-wikilinks.

This gem is part of the jekyll-bonsai project. 🎋

Installation

Follow the instructions for installing a jekyll plugin for jekyll-graph.

Usage

  1. Add {% jekyll_graph %} to the site head:
<head>

  ...

  {% jekyll_graph %}

</head>
  1. Add a graph div in your html where you want the graph to be rendered:
<div id="jekyll-graph"></div>
  1. Subclass JekyllGraph class in javascript like so:
import JekyllGraph from './jekyll-graph.js';

export default class JekyllGraphSubClass extends JekyllGraph {

  constructor() {
    super();
    // access graph with 'this.graph'
    // access graph div with 'this.graphDiv'
  }
  
  // ...
}

Call this.drawNetWeb() and this.drawTree() to actually draw the graph. You could do this simply on initialization or on a button click, etc.

Unless otherwise configured (see path vars below), the jekyll-graph.js file will be generated into _site/assets/js/.

Configuration

Default configs look like this:

graph:
  enabled: true
  exclude: []
  path:
    assets: "/assets"
    scripts: "/assets/js"
  net_web:
    enabled: true
    exclude:
      attrs: false
      links: false
    force:
      charge:
      strength_x:
      x_val:
      strength_y:
      y_val:
  tree:
    enabled: true
    force:
      charge:
      strength_x:
      x_val:
      strength_y:
      y_val:

enabled: Turn off the plugin by setting to false.

exclude: Exclude specific jekyll document types (posts, pages, collection_items).

path.assets: An optional custom assets location for graph assets to generate into. Location is relative to the root of the generated _site/ directory.

path.scripts: An optional custom scripts location for the graph scripts to generate into. Location is relative to the assets location in the _site/ directory (If assets_path is set, but scripts_path is not, the location will default to _site/<assets_path>/js/).

net_web.exclude.attrs and net_web.exclude.links: Determines whether wikilink attributes and/or links are added to the net-web graph from the link index.

tree.enabled and net_web.enabled: Toggles on/off the tree and net_web graphs, respectively. Be sure to disable graphs that are not in use.

tree.force and net_web.force: These are force variables from d3's simulation forces. You can check out the docs for details.

Force values will likely need to be played with depending on the div size and number of nodes. jekyll-bonsai currently uses these values:

graph:
  tree:
    dag_lvl_dist: 100
    force:
      charge: -100
      strength_x: 0.3
      x_val: 0.9
      strength_y: 0.1
      y_val: 0.9
  net_web:
    force:
      charge: -300
      strength_x: 0.3
      x_val: 0.75
      strength_y: 0.1
      y_val: 0.9

No configurations are strictly necessary for plugin defaults to work.

Colors

Graph colors are determined by css variables which may be defined like so -- any valid css color works (hex, rgba, etc.):

  /* nodes */
  /* glow */
  --graph-node-current-glow: yellow;
  --graph-node-tagged-glow: green;
  --graph-node-visited-glow: blue;
  /* color */
  --graph-node-stroke-color: grey;
  --graph-node-missing-color: transparent;
  --graph-node-unvisited-color: brown;
  --graph-node-visited-color: green;
  /* links */
  --graph-link-color: brown;
  --graph-particles-color: grey;
  /* label text */
  --graph-text-color: black;

Data

Graph data is generated in the following format:

For the net-web graph, graph-net-web.json,links are built from backlinks and attributed metadata generated in jekyll-wikilinks:

// graph-net-web.json
{
  "nodes": [
    {
      "id": "<some-id>",
      "url": "<relative-url>", // site.baseurl is handled for you here
      "label": "<note's-title>",
      "neighbors": {
          "nodes": [<neighbor-node-id>, ...],
          "links": [<neighbor-link-id>, ...],
      }
    },
    ...
  ],
  "links": [
    {
      "source": "<a-node-id>",
      "target": "<another-node-id>",
    },
    ...
  ]
}

For the tree graph, graph-tree.json, links are built from a tree data structure constructed in jekyll-namespaces:

// graph-tree.json
{
  "nodes": [
    {
      "id": "<some-id>",
      "url": "<lineage-url>", // site.baseurl wil be handled for you here
      "label": "<note's-title>",
      "lineage": {
          "nodes": [<lineage-node-id>, ...],
          "links": [<lineage-link-id>, ...],
      }
    },
    ...
  ],
  "links": [
    {
      "source": "<a-node-id>",
      "target": "<another-node-id>",
    },
    ...
  ]
}

Unless otherwise defined, both json files are generated into _site/assets/.