docsify-sigma

Visualize a graph in your docsify project using Sigma.js and Graphology.

Current versions of dependencies

• Sigma.js: 4.0.0-beta.5
• Graphology: 0.26.0

Note: Sigma.js v4 is chosen rather than v3.0.3 because it's far better documented.

Graphs supported

In this version of the plugin, only the graphs with this JSON structure are parsed:

{
  "nodes": [
    { "key": "page11", "label": "Le titre", "cluster": "0", "x": 643.8, "y": -770.3, "score": 28 }
    ...
  ],
  "edges": [
    ["page11", "page12"],
    ...
  ],
  "clusters": [
    { "key": "0", "color": "#6c3e81", "clusterLabel": "my favorite cluster" }
    ...
  ]
}

How to use

Quick start

1. Install and activate the plugin in your Docsify project

Install the plugin in your Docsify project by following the instructions in the Docsify documentation. You have two possibilities:

• Copy docsify-sigma.js in the plugin folder, then add this script line in your index.html:

<script src="plugins/docsify-sigma.js"></script>

OR

• Install using JSDELIVER CDN by adding this script line in your index.html:

<script src="https://cdn.jsdelivr.net/gh/julienbusset/docsify-sigma@v1.0.0/docsify-sigma.js"></script>

Then activate the plugin in the Docsify configuration:

    <!-- Configuration -->
    <script>
      window.$docsify = {
        […]
        docsifySigma: true,
      };

2. Add a graph in a page

Once the plugin is installed, put this line in your md file:

<div class="docsify-sigma" graph-data-url="path/to/graph.json"></div>

where path/to/graph.json is the path to your graph file.

If no graph-data-url attribute is specified, then it's default value is graph.json. It means that if you don't tell where the file is, then it will assumes that it's in the same directory and named graph.json.

You can put several graphs: just put one line for each graph.

Customization

You can add attributes to customize the graph. If omitted or incorrect, the default value is used.

Don't forget the quotes for values with letters or symbols. For numeric only values, don't use quotes.

To use the attribute attribute-name with the value "value", do this:

<div class="docsify-sigma" graph-data-url="path/to/graph.json" attribute-name="value"></div>

List of attributes

Attribute name	What for	Format	Default value	Exemples	Related doc
container-width	Adjust the width of the graph container	"n%" with n between 0 and 100 or "npx" with n an integer	"100%"	container-width="75%" container-width="500px"	n/a
container-height	Adjust the height of the graph container	"nvh" with n between 0 and 100 (vh stands for "percentage of viewport height") or "npx" with n an integer	"50vh"	container-width="70vh" container-width="300px"	n/a
min-node-size	Minimum size of a node, for automatic node size adjustment	integer	10	min-node-size=20	n/a
max-node-size	Maximum size of a node, for automatic node size adjustment	integer	50	max-node-size=150	n/a
edges-size	Thickness of edges	integer	1	edges-size=50	n/a
edges-color	Color of edges	"#xxx" or "#xxxxxx" with xxx or xxxxxx the HTML color code on 3 or 6 hexadecimal digits	"#ccc"	edges-color="#111" edges-color="#F08080"	n/a

Exemple

<div class="docsify-sigma" graph-data-url="path/to/graph.json" edges-size=10 container-height="70vh"></div>

Contribute

Please contribute to the development of this plugin :)

To run the regression tests:

1. Clone the repo localy.
2. Run a http server at the root of the cloned repo. For exemple, run python3 -m http.server in the cloned repo.
3. Access the served files in your browser at the /tests/ URI. For exemple, visit http://localhost:8000/tests/ if you runned the command in exemple at step 2.
4. Follow the instructions that have just appeared on your screen.
5. Adjust the tests if needed, and include these adjustments in your pull request.
6. Paste the results of the tests in your pull request.