Another Graph

[Kyusetzu]

Hello everyone.
Today I worked hard to make a graph alternative to the one Lisandra made.
I made the graph with python and wanted a solution that is more customizable.

Here is how I made it:

1. Install networkx, matplotlib & scipy

pip install networkx matplotlib scipy

2. Create a new python file in the root directory.
   I named mine makegraph.py.

import os
import re
import networkx as nx
import matplotlib

# Setting matplotlib's backend to 'Agg' to allow rendering without a display (e.g., when running on a server)
matplotlib.use("Agg")
import matplotlib.pyplot as plt
from matplotlib.patheffects import withStroke  # To create an outline effect for text

# Define path for the folder containing the documentation
path = "docs"

# Define colors for different elements of the graph
NODE_COLOR = "#a877c8"
NODE_BORDER_COLOR = "#723f93"
BACKGROUND_COLOR = "white"
EDGE_COLOR = "gray"
FONT_COLOR = "black"
FONT_OUTLINE_COLOR = "white"
TAG_NODE_COLOR = "#67c570"
TAG_BORDER_COLOR = "black"

# Define toggles to control various features
IS_TRANSPARENT = True  # Background transparency
SHOW_FILENAMES = False  # Display filenames on the nodes
SHOW_NODE_BORDER = True  # Show border around nodes
USE_TAGS = True  # Connect files using tags

# Define default node size and font size
node_size_default = 200
FONT_SIZE = 8

# Get all markdown files within the 'docs' folder
files = [
    os.path.join(root, filename)
    for root, _, filenames in os.walk(path)
    for filename in filenames
    if filename.endswith(".md")
]

# Extract titles from filenames without their extensions
file_titles = {f: os.path.splitext(os.path.basename(f))[0] for f in files}

# Create an empty graph
G = nx.Graph()

# Add titles as nodes to the graph
for title in file_titles.values():
    G.add_node(title)

# If tags are enabled, extract them and add as nodes
tags = set()
if USE_TAGS:
    # Regular expression pattern for tags (excluding hexadecimal colors)
    tag_pattern = r"#[\w\d_\-]+"  # Matches words like #tagname, sadly picks up EVERYTHING thats behind a hashtag
    for file in files:
        with open(file, "r", encoding="utf-8", errors="ignore") as f:
            content = f.read()
            file_tags = re.findall(tag_pattern, content)
            tags.update(file_tags)

    # Add unique tags to the graph
    for tag in tags:
        G.add_node(tag)

# Process each file: extract links and tags, and add respective edges to the graph
for file, title in file_titles.items():
    with open(file, "r", encoding="utf-8", errors="ignore") as f:
        content = f.read()
        
        # Connect files based on links within [[]]
        for match in re.findall(r"\[\[(.*?)\]\]", content):
            if match in file_titles.values() and title != match:
                G.add_edge(title, match)

        # If tags are enabled, connect files to their respective tags
        if USE_TAGS:
            for tag in tags:
                if tag in content:
                    G.add_edge(title, tag)

# Determine node size based on the number of connections (degree)
node_size = [node_size_default + (v * 10) for v in dict(G.degree()).values()]

# Determine position of each node using Kamada-Kawai layout (forces-based layout)
pos = nx.kamada_kawai_layout(G)

# Set up the graph visualization
plt.figure(figsize=(12, 12))

# Set the background color (or make it transparent)
if IS_TRANSPARENT:
    plt.gca().set_facecolor("none")
else:
    plt.gca().set_facecolor(BACKGROUND_COLOR)

# Differentiate between file nodes and tag nodes by color
node_colors = [TAG_NODE_COLOR if node in tags else NODE_COLOR for node in G.nodes()]
border_colors = [
    TAG_BORDER_COLOR
    if node in tags
    else (NODE_BORDER_COLOR if SHOW_NODE_BORDER else NODE_COLOR)
    for node in G.nodes()
]

# Draw the graph
nx.draw(
    G,
    pos,
    with_labels=False,
    node_size=node_size,
    node_color=node_colors,
    edge_color=EDGE_COLOR,
    edgecolors=border_colors,
    linewidths=1 if SHOW_NODE_BORDER else 0,
    alpha=0.9,
)

# If enabled, display filenames on their respective nodes
if SHOW_FILENAMES:
    for node, (x, y) in pos.items():
        plt.text(
            x,
            y,
            node,
            color=FONT_COLOR,
            fontsize=FONT_SIZE,
            ha="center",
            va="center",
            path_effects=[withStroke(linewidth=3, foreground=FONT_OUTLINE_COLOR)],
        )

# Check if there's an 'assets' folder inside 'docs'. If not, create one.
assets_path = os.path.join(path, "assets")
if not os.path.exists(assets_path):
    os.makedirs(assets_path)

# Save the visualized graph as a PNG image inside the 'assets' folder
plt.savefig(
    os.path.join(assets_path, "graph.png"),
    facecolor=("none" if IS_TRANSPARENT else BACKGROUND_COLOR),
    transparent=IS_TRANSPARENT,
)

3. Call the python script when building the page.
   The essentials you should have in your .github/workflows/ .yml file to run the script - you have to adjust your file accordingly.

name: Make Graph
on:
  push:
    branches:
      - master
      - main
permissions:
  contents: write
jobs:
  deploy:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v3
      - uses: actions/setup-python@v4
        with:
          python-version: 3.x
      - run: pip install networkx matplotlib scipy
      - run: python ./makegraph.py

The result should look like this:

Please note that this script is by no means perfect, there are still many issues with it, but at least it can be customized to your hearts content with adjusting the first few variables!

I will try to continue this script in the future.