MkDocs Network Graph Plugin

Add an interactive knowledge network graph to your Material for MkDocs documentation project

A powerful Material for MkDocs plugin that generates beautiful, interactive graph visualizations of your documentation structure and relationships.

Documentation • Quick Start • Configuration • Contributing

---

Table of Contents

• Features
• Quick Start
• Installation
• Configuration
• Customization
• Documentation
• Contributing
• License
• Acknowledgments

Features

Interactive Visualization	Smart Navigation	Fully Customizable	Lightweight
Interactive Graph Visualization of your documentation structure	Dual View Modes to switch between a full-site overview and local page connections	Theme Integration that seamlessly blends with Material for MkDocs	Performance Optimized with minimal impact on build times and a responsive design

Quick Start

Get up and running in under 2 minutes:

1. Install the plugin

pip install mkdocs-network-graph-plugin

2. Enable in your mkdocs.yml

plugins:
  - graph

3. Build your docs

mkdocs serve

That's it! Your documentation now includes an interactive graph visualization.

Installation

Using pip (recommended)

pip install mkdocs-network-graph-plugin

Using uv (faster)

uv pip install mkdocs-network-graph-plugin

Using pipx (isolated)

pipx install mkdocs-network-graph-plugin

Development Installation

For contributors, this is the recommended setup:

1. Clone the repository

   git clone https://github.com/develmusa/mkdocs-network-graph-plugin.git
   cd mkdocs-network-graph-plugin

2. Set up the development environment

   # Sync with the lockfile
   uv sync
   # Install required Python versions for testing
   uv python install 3.10 3.11 3.12 3.13
   # Install in editable mode with dev dependencies
   uv pip install -e '.[dev]'
   # Install pre-commit hooks
   uv run pre-commit install

For more details, see the developer guide.

Requirements

• Python: 3.10+
• MkDocs: Compatible with latest versions
• Theme: Designed for Material for MkDocs (v9.0.0+)

Configuration

Basic Configuration

plugins:
  - graph:
      name: "title"        # Use page titles for node names
      debug: false         # Disable debug logging

Advanced Configuration

plugins:
  - graph:
      name: "file_name"    # Use file names instead of titles
      debug: true          # Enable verbose logging for troubleshooting

Configuration Options

Option	Type	Default	Description
name	string	"title"	Node naming strategy: "title" or "file_name"
debug	boolean	false	Enable debug logging for development

Customization

Customize the graph appearance using CSS variables in your extra.css:

:root {
  /* Node styling */
  --md-graph-node-color: #1976d2;
  --md-graph-node-color--hover: #1565c0;
  --md-graph-node-color--current: #ff5722;

  /* Link styling */
  --md-graph-link-color: #757575;

  /* Text styling */
  --md-graph-text-color: #212121;
}

Available CSS Variables

Variable	Description	Default
--md-graph-node-color	Default node color	Theme primary
--md-graph-node-color--hover	Node hover color	Darker primary
--md-graph-node-color--current	Current page node color	Theme accent
--md-graph-link-color	Connection line color	Theme text (muted)
--md-graph-text-color	Node label text color	Theme text

Documentation

Comprehensive documentation is available at develmusa.github.io/mkdocs-network-graph-plugin

Documentation Sections

• Getting Started - Installation and basic setup
• Why Use a Graph? - Benefits and use cases
• How it Works - Technical implementation details
• Configuration - Complete configuration reference
• Customization - Styling and theming guide
• For Developers - Contributing and development guide

Contributing

We welcome contributions! For a complete guide on how to contribute, please see the developer guide.

To get started, set up your environment by following the Development Installation instructions. From there, you can run tests and linting using nox:

# Run tests
uv run nox -s tests

# Run linting
uv run nox -s lint

Contribution Guidelines

• Bug Reports: Use the issue tracker
• Feature Requests: Open an issue with your proposal
• Pull Requests: Fork, create a feature branch, and submit a PR
• Documentation: Help improve our docs

License

This project is licensed under the MIT License - see the LICENSE file for details

Acknowledgments

• mkdocs-obsidian-interactive-graph-plugin - Thank you for the inspiration and logos for the MkDocs graph visualization
• Material for MkDocs
• D3.js
• MkDocs

Related Projects

Explore other tools with Markdown documentation graph visualization:

• mkdocs-obsidian-interactive-graph-plugin
• Digital Garden - A comprehensive digital garden solution with graph visualization
• Foam - Personal knowledge management and sharing system with graph features

---

Star this project if you find it useful!

Made with AI and ❤️ by develmusa