{"id":18090813,"url":"https://github.com/wikibonsai/jekyll-graph","last_synced_at":"2025-07-10T07:34:07.086Z","repository":{"id":56878581,"uuid":"407635518","full_name":"wikibonsai/jekyll-graph","owner":"wikibonsai","description":"Add graph(s) support for jekyll.","archived":false,"fork":false,"pushed_at":"2023-10-06T16:23:21.000Z","size":222,"stargazers_count":9,"open_issues_count":3,"forks_count":1,"subscribers_count":2,"default_branch":"main","last_synced_at":"2025-07-01T10:06:16.197Z","etag":null,"topics":["d3","graph","hierarchy","jekyll","network","tree","web"],"latest_commit_sha":null,"homepage":"https://rubygems.org/gems/jekyll-graph","language":"Ruby","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"gpl-3.0","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/wikibonsai.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGELOG.md","contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null}},"created_at":"2021-09-17T18:00:58.000Z","updated_at":"2025-06-25T18:57:18.000Z","dependencies_parsed_at":"2022-08-20T11:40:18.431Z","dependency_job_id":null,"html_url":"https://github.com/wikibonsai/jekyll-graph","commit_stats":null,"previous_names":["manunamz/jekyll-graph"],"tags_count":11,"template":false,"template_full_name":null,"purl":"pkg:github/wikibonsai/jekyll-graph","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/wikibonsai%2Fjekyll-graph","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/wikibonsai%2Fjekyll-graph/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/wikibonsai%2Fjekyll-graph/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/wikibonsai%2Fjekyll-graph/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/wikibonsai","download_url":"https://codeload.github.com/wikibonsai/jekyll-graph/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/wikibonsai%2Fjekyll-graph/sbom","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":264545174,"owners_count":23625405,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["d3","graph","hierarchy","jekyll","network","tree","web"],"created_at":"2024-10-31T18:07:44.190Z","updated_at":"2025-07-10T07:34:07.061Z","avatar_url":"https://github.com/wikibonsai.png","language":"Ruby","readme":"# Jekyll-Graph\n\n[![A WikiBonsai Project](https://img.shields.io/badge/%F0%9F%8E%8B-A%20WikiBonsai%20Project-brightgreen)](https://github.com/wikibonsai/wikibonsai)\n[![Ruby Gem](https://img.shields.io/gem/v/jekyll-graph)](https://rubygems.org/gems/jekyll-graph)\n\n⚠️ This is gem is under active development! ⚠️\n\n⚠️ Expect breaking changes and surprises until otherwise noted (likely by v0.1.0 or v1.0.0). ⚠️\n\nJekyll-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).\n\n🏡 Build and maintain a treehouze to play in in your [WikiBonsai](https://github.com/wikibonsai/wikibonsai) digital garden.\n\n## Installation\n\nFollow the instructions for installing a [jekyll plugin](https://jekyllrb.com/docs/plugins/installation/) for `jekyll-graph`.\n\n## Usage\n\n1. Add `{% jekyll_graph %}` to the site head:\n\n```html\n\u003chead\u003e\n\n  ...\n\n  {% jekyll_graph %}\n\n\u003c/head\u003e\n```\n\n2. Add a graph div in your html where you want the graph to be rendered:\n\n```html\n\u003cdiv id=\"jekyll-graph\"\u003e\u003c/div\u003e\n```\n\n3. Subclass `JekyllGraph` class in javascript like so:\n\n```javascript\nimport JekyllGraph from './jekyll-graph.js';\n\nclass JekyllGraphSubClass extends JekyllGraph {\n\n  constructor() {\n    super();\n    // access graph with 'this.graph'\n    // access graph div with 'this.graphDiv'\n  }\n  \n  // ...\n}\n```\n\nThe 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.\n\n4. Create a class instance:\n\n```javascript\nvar graph = new JekyllGraphSubClass();\n```\n\n5. Call `drawWeb()` and/or `drawTree()` to actually draw the graph. You could do this simply on initialization or on a button click, etc.\n\n```javascript\n// on page load\n(() =\u003e {\n  graph.drawWeb();\n});\n\n// on button click\nthis.graphBtn.addEventListener('click', () =\u003e {\n  graph.drawTree();\n});\n```\n## Configuration\n\nDefault configs look like this:\n\n```yaml\ngraph:\n  enabled: true\n  exclude: []\n  path:\n    assets: \"/assets\"\n    scripts: \"/assets/js\"\n  web:\n    enabled: true\n    exclude:\n      attrs: false\n      links: false\n    force:\n      charge:\n      strength_x:\n      x_val:\n      strength_y:\n      y_val:\n  tree:\n    enabled: true\n    force:\n      charge:\n      strength_x:\n      x_val:\n      strength_y:\n      y_val:\n```\n\n`enabled`: Turn off the plugin by setting to `false`.\n\n`exclude`: Exclude specific jekyll document types (`posts`, `pages`, `collection_items`).\n\n`path.assets`: An optional custom assets location for graph assets to generate into. Location is relative to the root of the generated `_site/` directory.\n\n`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/\u003cassets_path\u003e/js/`).\n\n`web.exclude.attrs` and `web.exclude.links`: Determines whether wikilink attributes and/or links are added to the web graph from the link index.\n\n`tree.enabled` and `web.enabled`: Toggles on/off the `tree` and `web` graphs, respectively. Be sure to disable graphs that are not in use.\n\n`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).\n\nForce 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:\n\n```yaml\ngraph:\n  tree:\n    dag_lvl_dist: 100\n    force:\n      charge: -100\n      strength_x: 0.3\n      x_val: 0.9\n      strength_y: 0.1\n      y_val: 0.9\n  web:\n    force:\n      charge: -300\n      strength_x: 0.3\n      x_val: 0.75\n      strength_y: 0.1\n      y_val: 0.9\n```\n\nNo configurations are strictly necessary for plugin defaults to work.\n\n## Colors\n\nGraph colors are determined by css variables which may be defined like so -- any valid css color works (hex, rgba, etc.):\n\n```CSS\n/* make sure color vars are attached to the root of the html document */\nhtml {\n  /* nodes */\n  /* glow */\n  --graph-node-current-glow: yellow;\n  --graph-node-tagged-glow: green;\n  --graph-node-visited-glow: blue;\n  /* color */\n  --graph-node-stroke-color: grey;\n  --graph-node-missing-color: transparent;\n  --graph-node-unvisited-color: brown;\n  --graph-node-visited-color: green;\n  /* links */\n  --graph-link-color: brown;\n  --graph-particles-color: grey;\n  /* label text */\n  --graph-text-color: black;\n}\n```\n\n## Data\nGraph data is generated in the following format:\n\nFor the web graph, `graph-web.json`,`links` are built from `backlinks` and `attributed` metadata generated in `jekyll-wikilinks`:\n\n```json\n// graph-web.json\n{\n  \"nodes\": [\n    {\n      \"id\": \"\u003csome-id\u003e\",\n      \"url\": \"\u003crelative-url\u003e\", // site.baseurl is handled for you here\n      \"label\": \"\u003cnote's-title\u003e\",\n      \"neighbors\": {\n          \"nodes\": [\u003cneighbor-node-id\u003e, ...],\n          \"links\": [\u003cneighbor-link-id\u003e, ...],\n      }\n    },\n    ...\n  ],\n  \"links\": [\n    {\n      \"source\": \"\u003ca-node-id\u003e\",\n      \"target\": \"\u003canother-node-id\u003e\",\n    },\n    ...\n  ]\n}\n```\n\nFor the tree graph, `graph-tree.json`, `links` are built from a tree data structure constructed in `jekyll-namespaces`:\n\n```json\n// graph-tree.json\n{\n  \"nodes\": [\n    {\n      \"id\": \"\u003csome-id\u003e\",\n      \"url\": \"\u003clineage-url\u003e\", // site.baseurl wil be handled for you here\n      \"label\": \"\u003cnote's-title\u003e\",\n      \"lineage\": {\n          \"nodes\": [\u003clineage-node-id\u003e, ...],\n          \"links\": [\u003clineage-link-id\u003e, ...],\n      }\n    },\n    ...\n  ],\n  \"links\": [\n    {\n      \"source\": \"\u003ca-node-id\u003e\",\n      \"target\": \"\u003canother-node-id\u003e\",\n    },\n    ...\n  ]\n}\n```\n\nUnless otherwise defined, both json files are generated into `_site/assets/`.\n","funding_links":[],"categories":[],"sub_categories":[],"project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fwikibonsai%2Fjekyll-graph","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fwikibonsai%2Fjekyll-graph","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fwikibonsai%2Fjekyll-graph/lists"}