<div align="center">
# MkDocs Graph Plugin
**Add an interactive knowledge graph to your Material for MkDocs documentation project**
[](https://pypi.org/project/mkdocs-graph-plugin/)
[](https://pypi.org/project/mkdocs-graph-plugin/)
[](https://github.com/develmusa/mkdocs-graph-plugin/blob/main/LICENSE)
[](https://github.com/develmusa/mkdocs-graph-plugin/actions)
[](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>
Raw data
{
"_id": null,
"home_page": null,
"name": "mkdocs-graph-plugin",
"maintainer": null,
"docs_url": null,
"requires_python": ">=3.10",
"maintainer_email": null,
"keywords": "mkdocs, plugin, graph, documentation",
"author": null,
"author_email": "develmusa <develmusa@users.noreply.github.com>",
"download_url": "https://files.pythonhosted.org/packages/78/68/7d964bcf358ed7884dffaff12d45ad2dccbd0089ee0315a9dc7b91ea590b/mkdocs_graph_plugin-1.2.1.post1.dev0.tar.gz",
"platform": null,
"description": "<div align=\"center\">\n\n# MkDocs Graph Plugin\n\n**Add an interactive knowledge graph to your Material for MkDocs documentation project**\n\n[](https://pypi.org/project/mkdocs-graph-plugin/)\n[](https://pypi.org/project/mkdocs-graph-plugin/)\n[](https://github.com/develmusa/mkdocs-graph-plugin/blob/main/LICENSE)\n[](https://github.com/develmusa/mkdocs-graph-plugin/actions)\n[](https://develmusa.github.io/mkdocs-graph-plugin/)\n\n*A powerful [Material for MkDocs](https://squidfunk.github.io/mkdocs-material/) plugin that generates beautiful, interactive graph visualizations of your documentation structure and relationships.*\n\n[**Documentation**](https://develmusa.github.io/mkdocs-graph-plugin/) \u2022 [**Quick Start**](#quick-start) \u2022 [**Configuration**](#configuration) \u2022 [**Contributing**](#contributing)\n\n</div>\n\n---\n\n## Table of Contents\n\n- [Features](#features)\n- [Why Use a Graph?](#why-use-a-graph)\n- [Quick Start](#quick-start)\n- [Installation](#installation)\n- [Configuration](#configuration)\n- [Customization](#customization)\n- [Documentation](#documentation)\n- [Contributing](#contributing)\n- [License](#license)\n- [Acknowledgments](#acknowledgments)\n\n## Features\n\n<div align=\"center\">\n\n| **Interactive Visualization** | **Smart Navigation** | **Fully Customizable** | **Lightweight** |\n|:---:|:---:|:---:|:---:|\n| Beautiful, interactive graphs powered by D3.js | Full-site and local graph views | CSS variables for easy theming | Minimal dependencies, maximum performance |\n\n</div>\n\n### Key Capabilities\n\n- **Interactive Graph Visualization** - Creates stunning, interactive graphs of your documentation structure\n- **Dual View Modes** - Switch between full-site overview and local page connections\n- **Theme Integration** - Seamlessly integrates with Material for MkDocs themes\n- **Performance Optimized** - Lightweight with minimal impact on build times\n- **Highly Configurable** - Extensive customization options via CSS variables\n- **Responsive Design** - Works beautifully on desktop and mobile devices\n\n## Why Use a Graph?\n\nTraditional 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:\n\n- **Enhanced Discoverability** - Visualize connections between related content you might otherwise miss\n- **Better Understanding** - See the \"big picture\" of your documentation architecture\n- **Intuitive Navigation** - Jump between related topics with visual, contextual navigation\n- **Content Insights** - Identify documentation gaps and over-connected areas\n\n## Quick Start\n\nGet up and running in under 2 minutes:\n\n### 1. Install the plugin\n\n```bash\npip install mkdocs-graph-plugin\n```\n\n### 2. Enable in your `mkdocs.yml`\n\n```yaml\nplugins:\n - graph\n```\n\n### 3. Build your docs\n\n```bash\nmkdocs serve\n```\n\nThat's it! Your documentation now includes an interactive graph visualization.\n\n## Installation\n\n### Using pip (recommended)\n\n```bash\npip install mkdocs-graph-plugin\n```\n\n### Using uv (faster)\n\n```bash\nuv pip install mkdocs-graph-plugin\n```\n\n### Using pipx (isolated)\n\n```bash\npipx install mkdocs-graph-plugin\n```\n\n### Development Installation\n\nFor contributors and developers:\n\n```bash\ngit clone https://github.com/develmusa/mkdocs-graph-plugin.git\ncd mkdocs-graph-plugin\nuv pip install -e '.[dev]'\n```\n\n### Requirements\n\n- **Python**: 3.10+\n- **MkDocs**: Compatible with latest versions\n- **Theme**: Designed for [Material for MkDocs](https://squidfunk.github.io/mkdocs-material/) (v9.0.0+)\n\n## Configuration\n\n### Basic Configuration\n\n```yaml\nplugins:\n - graph:\n name: \"title\" # Use page titles for node names\n debug: false # Disable debug logging\n```\n\n### Advanced Configuration\n\n```yaml\nplugins:\n - graph:\n name: \"file_name\" # Use file names instead of titles\n debug: true # Enable verbose logging for troubleshooting\n```\n\n### Configuration Options\n\n| Option | Type | Default | Description |\n|--------|------|---------|-------------|\n| `name` | `string` | `\"title\"` | Node naming strategy: `\"title\"` or `\"file_name\"` |\n| `debug` | `boolean` | `false` | Enable debug logging for development |\n\n## Customization\n\nCustomize the graph appearance using CSS variables in your `extra.css`:\n\n```css\n:root {\n /* Node styling */\n --md-graph-node-color: #1976d2;\n --md-graph-node-color--hover: #1565c0;\n --md-graph-node-color--current: #ff5722;\n\n /* Link styling */\n --md-graph-link-color: #757575;\n\n /* Text styling */\n --md-graph-text-color: #212121;\n}\n```\n\n### Available CSS Variables\n\n| Variable | Description | Default |\n|----------|-------------|---------|\n| `--md-graph-node-color` | Default node color | Theme primary |\n| `--md-graph-node-color--hover` | Node hover color | Darker primary |\n| `--md-graph-node-color--current` | Current page node color | Theme accent |\n| `--md-graph-link-color` | Connection line color | Theme text (muted) |\n| `--md-graph-text-color` | Node label text color | Theme text |\n\n## Documentation\n\nComprehensive documentation is available at **[develmusa.github.io/mkdocs-graph-plugin](https://develmusa.github.io/mkdocs-graph-plugin/)**\n\n### Documentation Sections\n\n- **[Getting Started](https://develmusa.github.io/mkdocs-graph-plugin/tutorials/getting-started/)** - Installation and basic setup\n- **[Why Use a Graph?](https://develmusa.github.io/mkdocs-graph-plugin/explanation/why-use-a-graph/)** - Benefits and use cases\n- **[How it Works](https://develmusa.github.io/mkdocs-graph-plugin/explanation/how-it-works/)** - Technical implementation details\n- **[Configuration](https://develmusa.github.io/mkdocs-graph-plugin/reference/configuration/)** - Complete configuration reference\n- **[Customization](https://develmusa.github.io/mkdocs-graph-plugin/how-to/customization/)** - Styling and theming guide\n- **[For Developers](https://develmusa.github.io/mkdocs-graph-plugin/how-to/for-developers/)** - Contributing and development guide\n\n## Contributing\n\nWe welcome contributions! Here's how to get started:\n\n### Development Setup\n\n1. **Clone the repository**\n\n ```bash\n git clone https://github.com/develmusa/mkdocs-graph-plugin.git\n cd mkdocs-graph-plugin\n ```\n\n2. **Install development dependencies**\n\n ```bash\n uv pip install -e '.[dev]'\n ```\n\n3. **Run tests**\n\n ```bash\n uv run pytest\n ```\n\n4. **Check code style**\n\n ```bash\n uv run ruff check .\n uv run ruff format .\n ```\n\n### Contribution Guidelines\n\n- **Bug Reports**: Use the [issue tracker](https://github.com/develmusa/mkdocs-graph-plugin/issues)\n- **Feature Requests**: Open an issue with your proposal\n- **Pull Requests**: Fork, create a feature branch, and submit a PR\n- **Documentation**: Help improve our docs\n\n### Testing\n\n```bash\n# Run all tests\nuv run pytest\n\n# Run with coverage\nuv run pytest --cov=mkdocs_graph_plugin\n\n# Run specific test file\nuv run pytest tests/test_plugin.py\n```\n\n## License\n\nThis project is licensed under the **MIT License** - see the [LICENSE](https://github.com/develmusa/mkdocs-graph-plugin/blob/main/LICENSE) file for details\n\n## Acknowledgments\n\n- **[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\n- **[Material for MkDocs](https://squidfunk.github.io/mkdocs-material/)**\n- **[D3.js](https://d3js.org/)**\n- **[MkDocs](https://www.mkdocs.org/)**\n\n### Related Projects\n\nExplore other tools with Markdown documentation graph visualization:\n\n- **[mkdocs-obsidian-interactive-graph-plugin](https://github.com/daxcore/mkdocs-obsidian-interactive-graph-plugin)**\n- **[Digital Garden](https://dg-docs.ole.dev/)** - A comprehensive digital garden solution with graph visualization\n- **[Foam](https://foambubble.github.io/foam/user/features/graph-visualization.html)** - Personal knowledge management and sharing system with graph features\n\n---\n\n<div align=\"center\">\n\n**[Star this project](https://github.com/develmusa/mkdocs-graph-plugin)** if you find it useful!\n\nMade with AI and \u2764\ufe0f by [develmusa](https://github.com/develmusa)\n\n</div>\n",
"bugtrack_url": null,
"license": "MIT",
"summary": "A MkDocs plugin to generate an interactive graph of your documentation.",
"version": "1.2.1.post1.dev0",
"project_urls": {
"Documentation": "https://develmusa.github.io/mkdocs-graph-plugin/",
"Homepage": "https://github.com/develmusa/mkdocs-graph-plugin",
"Issues": "https://github.com/develmusa/mkdocs-graph-plugin/issues",
"Repository": "https://github.com/develmusa/mkdocs-graph-plugin"
},
"split_keywords": [
"mkdocs",
" plugin",
" graph",
" documentation"
],
"urls": [
{
"comment_text": null,
"digests": {
"blake2b_256": "b9a835679641401fee5d0f552a15331dc338e6afed984e9883753f45aec10c44",
"md5": "cf3b651b3381f1ebaf2c19d4adb3be55",
"sha256": "1ce929d6f9bcb460b6899302bc6857e6480bb3d893acce4f7e35110d268b84f4"
},
"downloads": -1,
"filename": "mkdocs_graph_plugin-1.2.1.post1.dev0-py3-none-any.whl",
"has_sig": false,
"md5_digest": "cf3b651b3381f1ebaf2c19d4adb3be55",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": ">=3.10",
"size": 16000,
"upload_time": "2025-08-21T10:38:40",
"upload_time_iso_8601": "2025-08-21T10:38:40.358783Z",
"url": "https://files.pythonhosted.org/packages/b9/a8/35679641401fee5d0f552a15331dc338e6afed984e9883753f45aec10c44/mkdocs_graph_plugin-1.2.1.post1.dev0-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": null,
"digests": {
"blake2b_256": "78687d964bcf358ed7884dffaff12d45ad2dccbd0089ee0315a9dc7b91ea590b",
"md5": "e1b528f5571c0387cb2860a40405fb52",
"sha256": "e0ec9a7abe112ec58820ec92d6d9c4a1321556ef6f6f9649eba09c68c5f5f083"
},
"downloads": -1,
"filename": "mkdocs_graph_plugin-1.2.1.post1.dev0.tar.gz",
"has_sig": false,
"md5_digest": "e1b528f5571c0387cb2860a40405fb52",
"packagetype": "sdist",
"python_version": "source",
"requires_python": ">=3.10",
"size": 63399,
"upload_time": "2025-08-21T10:38:41",
"upload_time_iso_8601": "2025-08-21T10:38:41.867238Z",
"url": "https://files.pythonhosted.org/packages/78/68/7d964bcf358ed7884dffaff12d45ad2dccbd0089ee0315a9dc7b91ea590b/mkdocs_graph_plugin-1.2.1.post1.dev0.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2025-08-21 10:38:41",
"github": true,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"github_user": "develmusa",
"github_project": "mkdocs-graph-plugin",
"travis_ci": false,
"coveralls": false,
"github_actions": true,
"lcname": "mkdocs-graph-plugin"
}
JSON
