Ecosyste.ms: Awesome
An open API service indexing awesome lists of open source software.
https://github.com/wikibonsai/jekyll-graph
Add graph(s) support for jekyll.
https://github.com/wikibonsai/jekyll-graph
d3 graph hierarchy jekyll network tree web
Last synced: 15 days ago
JSON representation
Add graph(s) support for jekyll.
- Host: GitHub
- URL: https://github.com/wikibonsai/jekyll-graph
- Owner: wikibonsai
- License: gpl-3.0
- Created: 2021-09-17T18:00:58.000Z (about 3 years ago)
- Default Branch: main
- Last Pushed: 2023-10-06T16:23:21.000Z (about 1 year ago)
- Last Synced: 2024-10-31T13:30:07.262Z (15 days ago)
- Topics: d3, graph, hierarchy, jekyll, network, tree, web
- Language: Ruby
- Homepage: https://rubygems.org/gems/jekyll-graph
- Size: 217 KB
- Stars: 10
- Watchers: 2
- Forks: 1
- Open Issues: 3
-
Metadata Files:
- Readme: README.md
- Changelog: CHANGELOG.md
- License: LICENSE
Awesome Lists containing this project
README
# Jekyll-Graph
[](https://github.com/wikibonsai/wikibonsai)
[](https://rubygems.org/gems/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-semtree`](https://github.com/wikibonsai/jekyll-semtree) and links for the web graph from [`jekyll-wikirefs`](https://github.com/wikibonsai/jekyll-wikirefs) (legacy versions from [`jekyll-namespaces`](https://github.com/manunamz/jekyll-namespaces) and [`jekyll-wikilinks`](https://github.com/manunamz/jekyll-wikilinks) respectively).
🏡 Build and maintain a treehouze to play in in your [WikiBonsai](https://github.com/wikibonsai/wikibonsai) digital garden.
## Installation
Follow the instructions for installing a [jekyll plugin](https://jekyllrb.com/docs/plugins/installation/) for `jekyll-graph`.
## Usage
1. Add `{% jekyll_graph %}` to the site head:
```html
...
{% jekyll_graph %}
```
2. Add a graph div in your html where you want the graph to be rendered:
```html
```
3. Subclass `JekyllGraph` class in javascript like so:
```javascript
import JekyllGraph from './jekyll-graph.js';
class JekyllGraphSubClass extends JekyllGraph {
constructor() {
super();
// access graph with 'this.graph'
// access graph div with 'this.graphDiv'
}
// ...
}
```
The import should point to the `jekyll-graph.js` javascript file generated by the plugin. Unless otherwise configured (see `path` vars below), the `jekyll-graph.js` file will be generated into `_site/assets/js/`. The sample javascript snippet above is presumed to be generated into `_site/assets/js/` as well.
4. Create a class instance:
```javascript
var graph = new JekyllGraphSubClass();
```
5. Call `drawWeb()` and/or `drawTree()` to actually draw the graph. You could do this simply on initialization or on a button click, etc.
```javascript
// on page load
(() => {
graph.drawWeb();
});
// on button click
this.graphBtn.addEventListener('click', () => {
graph.drawTree();
});
```
## Configuration
Default configs look like this:
```yaml
graph:
enabled: true
exclude: []
path:
assets: "/assets"
scripts: "/assets/js"
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//js/`).
`web.exclude.attrs` and `web.exclude.links`: Determines whether wikilink attributes and/or links are added to the web graph from the link index.
`tree.enabled` and `web.enabled`: Toggles on/off the `tree` and `web` graphs, respectively. Be sure to disable graphs that are not in use.
`tree.force` and `web.force`: These are force variables from d3's simulation forces. You can check out the [docs for details](https://github.com/d3/d3-force#simulation_force).
Force values will likely need to be played with depending on the div size and number of nodes. [jekyll-bonsai](https://manunamz.github.io/jekyll-bonsai/) currently uses these values:
```yaml
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
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.):
```CSS
/* make sure color vars are attached to the root of the html document */
html {
/* 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 web graph, `graph-web.json`,`links` are built from `backlinks` and `attributed` metadata generated in `jekyll-wikilinks`:
```json
// graph-web.json
{
"nodes": [
{
"id": "",
"url": "", // site.baseurl is handled for you here
"label": "",
"neighbors": {
"nodes": [, ...],
"links": [, ...],
}
},
...
],
"links": [
{
"source": "",
"target": "",
},
...
]
}
```
For the tree graph, `graph-tree.json`, `links` are built from a tree data structure constructed in `jekyll-namespaces`:
```json
// graph-tree.json
{
"nodes": [
{
"id": "",
"url": "", // site.baseurl wil be handled for you here
"label": "",
"lineage": {
"nodes": [, ...],
"links": [, ...],
}
},
...
],
"links": [
{
"source": "",
"target": "",
},
...
]
}
```
Unless otherwise defined, both json files are generated into `_site/assets/`.