Advanced Configuration¶

This page covers advanced configuration options for the sphinx-visualized extension. For basic setup, see Getting started.

Configuring Link Clusters¶

Clusters allow you to group pages in the link graph visualization based on glob patterns or directory structure. Pages in the same cluster are colored identically in the visualization, making it easy to understand the organization of your documentation.

Basic Cluster Setup¶

Add cluster configuration to your conf.py:

visualized_clusters = [
    {
        "name": "Getting Started",
        "patterns": ["index", "getting-started"]
    },
    {
        "name": "API Documentation",
        "patterns": ["api/*"]
    },
    {
        "name": "Examples",
        "patterns": ["tutorials/*", "examples/*"]
    }
]

Each cluster requires:

name (required): Display name shown in the cluster legend
patterns (required): List of glob patterns to match page paths

Pattern Matching¶

Patterns use standard glob syntax to match page paths:

Exact match: "index" matches only the index page
Wildcard: "api/*" matches all direct children of the api directory
Recursive: "docs/**/*" matches all pages under docs recursively
First match wins: If a page matches multiple patterns across different clusters, it’s assigned to the first matching cluster
Unclustered pages: Pages that don’t match any pattern use the default color

Automatic Clustering¶

For projects with a clear directory structure, you can enable automatic clustering instead of manually defining patterns:

visualized_auto_cluster = True

With auto-clustering enabled:

Pages in subdirectories are automatically grouped by their first directory component
For example, tutorials/intro.html and tutorials/advanced.html both get assigned to a cluster named “tutorials”
Root-level pages (like index.html) remain unclustered
You can combine auto-clustering with manual clusters - manual patterns take precedence

Integrating External Projects¶

Integrate documentation from other Sphinx projects that also use the sphinx-visualized extension:

intersphinx_mapping = {
    "sphinx": ("https://www.sphinx-doc.org/en/master/", None),
    "python": ("https://docs.python.org/3/", None),
}

visualized_projects = ['sphinx']

Note

Each project name must match an entry in your intersphinx_mapping.

GraphSON Export¶

The extension automatically generates a GraphSON v3.0 format file compatible with Apache TinkerPop and graph analysis tools:

/_static/sphinx-visualized/graphson.json

Use Cases:

Import into Apache TinkerPop for advanced graph queries
Analyze documentation structure with graph algorithms
Custom visualization with other graph libraries
Integration with graph databases
Documentation metrics and analytics