mkdocs-graph-plugin 1.2.8
A MkDocs plugin to generate an interactive graph of your documentation.
License: MIT
Requires Python: >=3.10
Keywords: mkdocs, plugin, graph, documentation

<div align="center">

# MkDocs Graph Plugin

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

[![PyPI - Version](https://img.shields.io/pypi/v/mkdocs-graph-plugin)](https://pypi.org/project/mkdocs-graph-plugin/)
[![PyPI - Python Version](https://img.shields.io/pypi/pyversions/mkdocs-graph-plugin)](https://pypi.org/project/mkdocs-graph-plugin/)
[![GitHub License](https://img.shields.io/github/license/develmusa/mkdocs-graph-plugin)](https://github.com/develmusa/mkdocs-graph-plugin/blob/main/LICENSE)
[![GitHub Actions Workflow Status](https://img.shields.io/github/actions/workflow/status/develmusa/mkdocs-graph-plugin/ci.yaml)](https://github.com/develmusa/mkdocs-graph-plugin/actions)
[![Documentation](https://img.shields.io/badge/docs-mkdocs-blue)](https://develmusa.github.io/mkdocs-graph-plugin/)

*A powerful [Material for MkDocs](https://squidfunk.github.io/mkdocs-material/) plugin that generates beautiful, interactive graph visualizations of your documentation structure and relationships.*

[**Documentation**](https://develmusa.github.io/mkdocs-graph-plugin/) • [**Quick Start**](#quick-start) • [**Configuration**](#configuration) • [**Contributing**](#contributing)

</div>

---

## Table of Contents

- [Features](#features)
- [Why Use a Graph?](#why-use-a-graph)
- [Quick Start](#quick-start)
- [Installation](#installation)
- [Configuration](#configuration)
- [Customization](#customization)
- [Documentation](#documentation)
- [Contributing](#contributing)
- [License](#license)
- [Acknowledgments](#acknowledgments)

## Features

<div align="center">

| **Interactive Visualization** | **Smart Navigation** | **Fully Customizable** | **Lightweight** |
|:---:|:---:|:---:|:---:|
| Beautiful, interactive graphs powered by D3.js | Full-site and local graph views | CSS variables for easy theming | Minimal dependencies, maximum performance |

</div>

### Key Capabilities

- **Interactive Graph Visualization** - Creates stunning, interactive graphs of your documentation structure
- **Dual View Modes** - Switch between full-site overview and local page connections
- **Theme Integration** - Seamlessly integrates with Material for MkDocs themes
- **Performance Optimized** - Lightweight with minimal impact on build times
- **Highly Configurable** - Extensive customization options via CSS variables
- **Responsive Design** - Works beautifully on desktop and mobile devices

## Why Use a Graph?

Traditional documentation follows a linear, hierarchical structure that can make it difficult to discover relationships between topics. A graph visualization transforms your docs into an interconnected knowledge network, offering:

- **Enhanced Discoverability** - Visualize connections between related content you might otherwise miss
- **Better Understanding** - See the "big picture" of your documentation architecture
- **Intuitive Navigation** - Jump between related topics with visual, contextual navigation
- **Content Insights** - Identify documentation gaps and over-connected areas

## Quick Start

Get up and running in under 2 minutes:

### 1. Install the plugin

```bash
pip install mkdocs-graph-plugin
```

### 2. Enable in your `mkdocs.yml`

```yaml
plugins:
  - graph
```

### 3. Build your docs

```bash
mkdocs serve
```

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

## Installation

### Using pip (recommended)

```bash
pip install mkdocs-graph-plugin
```

### Using uv (faster)

```bash
uv pip install mkdocs-graph-plugin
```

### Using pipx (isolated)

```bash
pipx install mkdocs-graph-plugin
```

### Development Installation

For contributors and developers:

```bash
git clone https://github.com/develmusa/mkdocs-graph-plugin.git
cd mkdocs-graph-plugin
uv pip install -e '.[dev]'
```

### Requirements

- **Python**: 3.10+
- **MkDocs**: Compatible with latest versions
- **Theme**: Designed for [Material for MkDocs](https://squidfunk.github.io/mkdocs-material/) (v9.0.0+)

## Configuration

### Basic Configuration

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

### Advanced Configuration

```yaml
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`:

```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-graph-plugin](https://develmusa.github.io/mkdocs-graph-plugin/)**

### Documentation Sections

- **[Getting Started](https://develmusa.github.io/mkdocs-graph-plugin/tutorials/getting-started/)** - Installation and basic setup
- **[Why Use a Graph?](https://develmusa.github.io/mkdocs-graph-plugin/explanation/why-use-a-graph/)** - Benefits and use cases
- **[How it Works](https://develmusa.github.io/mkdocs-graph-plugin/explanation/how-it-works/)** - Technical implementation details
- **[Configuration](https://develmusa.github.io/mkdocs-graph-plugin/reference/configuration/)** - Complete configuration reference
- **[Customization](https://develmusa.github.io/mkdocs-graph-plugin/how-to/customization/)** - Styling and theming guide
- **[For Developers](https://develmusa.github.io/mkdocs-graph-plugin/how-to/for-developers/)** - Contributing and development guide

## Contributing

We welcome contributions! Here's how to get started:

### Development Setup

1. **Clone the repository**

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

2. **Install development dependencies**

   ```bash
   uv pip install -e '.[dev]'
   ```

3. **Run tests**

   ```bash
   uv run pytest
   ```

4. **Check code style**

   ```bash
   uv run ruff check .
   uv run ruff format .
   ```

### Contribution Guidelines

- **Bug Reports**: Use the [issue tracker](https://github.com/develmusa/mkdocs-graph-plugin/issues)
- **Feature Requests**: Open an issue with your proposal
- **Pull Requests**: Fork, create a feature branch, and submit a PR
- **Documentation**: Help improve our docs

### Testing

```bash
# Run all tests
uv run pytest

# Run with coverage
uv run pytest --cov=mkdocs_graph_plugin

# Run specific test file
uv run pytest tests/test_plugin.py
```

## License

This project is licensed under the **MIT License** - see the [LICENSE](https://github.com/develmusa/mkdocs-graph-plugin/blob/main/LICENSE) file for details

## Acknowledgments

- **[mkdocs-obsidian-interactive-graph-plugin](https://github.com/daxcore/mkdocs-obsidian-interactive-graph-plugin)** - Thank you for the inspiration and logos for the MkDocs graph visualization
- **[Material for MkDocs](https://squidfunk.github.io/mkdocs-material/)**
- **[D3.js](https://d3js.org/)**
- **[MkDocs](https://www.mkdocs.org/)**

### Related Projects

Explore other tools with Markdown documentation graph visualization:

- **[mkdocs-obsidian-interactive-graph-plugin](https://github.com/daxcore/mkdocs-obsidian-interactive-graph-plugin)**
- **[Digital Garden](https://dg-docs.ole.dev/)** - A comprehensive digital garden solution with graph visualization
- **[Foam](https://foambubble.github.io/foam/user/features/graph-visualization.html)** - Personal knowledge management and sharing system with graph features

---

<div align="center">

**[Star this project](https://github.com/develmusa/mkdocs-graph-plugin)** if you find it useful!

Made with AI and ❤️ by [develmusa](https://github.com/develmusa)

</div>