---

Table of Contents

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

Features

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

As part of the package, the plugin looks for the key site_url in order to create the appropriate URLs to link and create the graphs. If you are experiencing an empty graph, enter a URL along with the protocol to your mkdocs.yml file. E.g.:

site_url: "https://example.com/username/repository"

If you are using mkdocs serve to preview your website, you may wish to pass an address argument. E.g., mkdocs serve -a localhost:8000

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

---