{"id":31048929,"url":"https://github.com/develmusa/mkdocs-network-graph-plugin","last_synced_at":"2025-09-14T21:24:29.884Z","repository":{"id":314279509,"uuid":"1042049822","full_name":"develmusa/mkdocs-network-graph-plugin","owner":"develmusa","description":"A MkDocs plugin that generates interactive network graph visualizations of your documentation structure, showing relationships between pages.","archived":false,"fork":false,"pushed_at":"2025-09-11T15:02:33.000Z","size":17073,"stargazers_count":0,"open_issues_count":0,"forks_count":1,"subscribers_count":0,"default_branch":"main","last_synced_at":"2025-09-11T16:14:51.057Z","etag":null,"topics":["material-for-mkdocs","mkdocs","mkdocs-plugin"],"latest_commit_sha":null,"homepage":"https://develmusa.github.io/mkdocs-network-graph-plugin/","language":"Python","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/develmusa.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGELOG.md","contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":null,"dco":null,"cla":null}},"created_at":"2025-08-21T12:07:57.000Z","updated_at":"2025-09-11T15:02:36.000Z","dependencies_parsed_at":"2025-09-11T16:25:40.057Z","dependency_job_id":null,"html_url":"https://github.com/develmusa/mkdocs-network-graph-plugin","commit_stats":null,"previous_names":["develmusa/mkdocs-network-graph-plugin"],"tags_count":4,"template":false,"template_full_name":null,"purl":"pkg:github/develmusa/mkdocs-network-graph-plugin","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/develmusa%2Fmkdocs-network-graph-plugin","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/develmusa%2Fmkdocs-network-graph-plugin/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/develmusa%2Fmkdocs-network-graph-plugin/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/develmusa%2Fmkdocs-network-graph-plugin/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/develmusa","download_url":"https://codeload.github.com/develmusa/mkdocs-network-graph-plugin/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/develmusa%2Fmkdocs-network-graph-plugin/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":275024527,"owners_count":25392540,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","status":"online","status_checked_at":"2025-09-13T02:00:10.085Z","response_time":70,"last_error":null,"robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":true,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["material-for-mkdocs","mkdocs","mkdocs-plugin"],"created_at":"2025-09-14T21:24:24.565Z","updated_at":"2025-09-14T21:24:29.844Z","avatar_url":"https://github.com/develmusa.png","language":"Python","funding_links":[],"categories":[],"sub_categories":[],"readme":"\u003cdiv align=\"center\"\u003e\r\n\r\n# MkDocs Network Graph Plugin\r\n\r\n**Add an interactive knowledge network graph to your Material for MkDocs documentation project**\r\n\r\n[![PyPI - Version](https://img.shields.io/pypi/v/mkdocs-network-graph-plugin)](https://pypi.org/project/mkdocs-network-graph-plugin/)\r\n[![PyPI - Python Version](https://img.shields.io/pypi/pyversions/mkdocs-network-graph-plugin)](https://pypi.org/project/mkdocs-network-graph-plugin/)\r\n[![GitHub License](https://img.shields.io/github/license/develmusa/mkdocs-network-graph-plugin)](https://github.com/develmusa/mkdocs-network-graph-plugin/blob/main/LICENSE)\r\n[![GitHub Actions Workflow Status](https://img.shields.io/github/actions/workflow/status/develmusa/mkdocs-network-graph-plugin/ci.yaml)](https://github.com/develmusa/mkdocs-network-graph-plugin/actions)\r\n[![Documentation](https://img.shields.io/badge/docs-mkdocs-blue)](https://develmusa.github.io/mkdocs-network-graph-plugin/)\r\n\r\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.*\r\n\r\n![demo](https://raw.githubusercontent.com/develmusa/mkdocs-network-graph-plugin/main/docs/assets/demo.gif)\r\n\r\n[**Documentation**](https://develmusa.github.io/mkdocs-network-graph-plugin/) • [**Quick Start**](#quick-start) • [**Configuration**](#configuration) • [**Contributing**](#contributing)\r\n\r\n\u003c/div\u003e\r\n\r\n---\r\n\r\n## Table of Contents\r\n\r\n- [Features](#features)\r\n- [Quick Start](#quick-start)\r\n- [Installation](#installation)\r\n- [Configuration](#configuration)\r\n- [Customization](#customization)\r\n- [Documentation](#documentation)\r\n- [Contributing](#contributing)\r\n- [License](#license)\r\n- [Acknowledgments](#acknowledgments)\r\n\r\n## Features\r\n\r\n\u003cdiv align=\"center\"\u003e\r\n\r\n| **Interactive Visualization** | **Smart Navigation** | **Fully Customizable** | **Lightweight** |\r\n|:---:|:---:|:---:|:---:|\r\n| **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 |\r\n\r\n\u003c/div\u003e\r\n\r\n## Quick Start\r\n\r\nGet up and running in under 2 minutes:\r\n\r\n### 1. Install the plugin\r\n\r\n```bash\r\npip install mkdocs-network-graph-plugin\r\n```\r\n\r\n### 2. Enable in your `mkdocs.yml`\r\n\r\n```yaml\r\nplugins:\r\n  - graph\r\n```\r\n\r\n### 3. Build your docs\r\n\r\n```bash\r\nmkdocs serve\r\n```\r\n\r\nThat's it! Your documentation now includes an interactive graph visualization.\r\n\r\n## Installation\r\n\r\n### Using pip (recommended)\r\n\r\n```bash\r\npip install mkdocs-network-graph-plugin\r\n```\r\n\r\n### Using uv (faster)\r\n\r\n```bash\r\nuv pip install mkdocs-network-graph-plugin\r\n```\r\n\r\n### Using pipx (isolated)\r\n\r\n```bash\r\npipx install mkdocs-network-graph-plugin\r\n```\r\n\r\n### Development Installation\r\n\r\nFor contributors, this is the recommended setup:\r\n\r\n1. **Clone the repository**\r\n\r\n    ```bash\r\n    git clone https://github.com/develmusa/mkdocs-network-graph-plugin.git\r\n    cd mkdocs-network-graph-plugin\r\n    ```\r\n\r\n2. **Set up the development environment**\r\n\r\n    ```bash\r\n    # Sync with the lockfile\r\n    uv sync\r\n    # Install required Python versions for testing\r\n    uv python install 3.10 3.11 3.12 3.13\r\n    # Install in editable mode with dev dependencies\r\n    uv pip install -e '.[dev]'\r\n    # Install pre-commit hooks\r\n    uv run pre-commit install\r\n    ```\r\n\r\nFor more details, see the [developer guide](https://develmusa.github.io/mkdocs-network-graph-plugin/how-to/for-developers/).\r\n\r\n### Requirements\r\n\r\n- **Python**: 3.10+\r\n- **MkDocs**: Compatible with latest versions\r\n- **Theme**: Designed for [Material for MkDocs](https://squidfunk.github.io/mkdocs-material/) (v9.0.0+)\r\n\r\n## Configuration\r\n\r\n### Basic Configuration\r\n\r\n```yaml\r\nplugins:\r\n  - graph:\r\n      name: \"title\"        # Use page titles for node names\r\n      debug: false         # Disable debug logging\r\n```\r\n\r\n### Advanced Configuration\r\n\r\n```yaml\r\nplugins:\r\n  - graph:\r\n      name: \"file_name\"    # Use file names instead of titles\r\n      debug: true          # Enable verbose logging for troubleshooting\r\n```\r\n\r\n### Configuration Options\r\n\r\n| Option | Type | Default | Description |\r\n|--------|------|---------|-------------|\r\n| `name` | `string` | `\"title\"` | Node naming strategy: `\"title\"` or `\"file_name\"` |\r\n| `debug` | `boolean` | `false` | Enable debug logging for development |\r\n\r\n## Customization\r\n\r\nCustomize the graph appearance using CSS variables in your `extra.css`:\r\n\r\n```css\r\n:root {\r\n  /* Node styling */\r\n  --md-graph-node-color: #1976d2;\r\n  --md-graph-node-color--hover: #1565c0;\r\n  --md-graph-node-color--current: #ff5722;\r\n\r\n  /* Link styling */\r\n  --md-graph-link-color: #757575;\r\n\r\n  /* Text styling */\r\n  --md-graph-text-color: #212121;\r\n}\r\n```\r\n\r\n### Available CSS Variables\r\n\r\n| Variable | Description | Default |\r\n|----------|-------------|---------|\r\n| `--md-graph-node-color` | Default node color | Theme primary |\r\n| `--md-graph-node-color--hover` | Node hover color | Darker primary |\r\n| `--md-graph-node-color--current` | Current page node color | Theme accent |\r\n| `--md-graph-link-color` | Connection line color | Theme text (muted) |\r\n| `--md-graph-text-color` | Node label text color | Theme text |\r\n\r\n## Documentation\r\n\r\nComprehensive documentation is available at **[develmusa.github.io/mkdocs-network-graph-plugin](https://develmusa.github.io/mkdocs-network-graph-plugin/)**\r\n\r\n### Documentation Sections\r\n\r\n- **[Getting Started](https://develmusa.github.io/mkdocs-network-graph-plugin/tutorials/getting-started/)** - Installation and basic setup\r\n- **[Why Use a Graph?](https://develmusa.github.io/mkdocs-network-graph-plugin/explanation/why-use-a-graph/)** - Benefits and use cases\r\n- **[How it Works](https://develmusa.github.io/mkdocs-network-graph-plugin/explanation/how-it-works/)** - Technical implementation details\r\n- **[Configuration](https://develmusa.github.io/mkdocs-network-graph-plugin/reference/configuration/)** - Complete configuration reference\r\n- **[Customization](https://develmusa.github.io/mkdocs-network-graph-plugin/how-to/customization/)** - Styling and theming guide\r\n- **[For Developers](https://develmusa.github.io/mkdocs-network-graph-plugin/how-to/for-developers/)** - Contributing and development guide\r\n\r\n## Contributing\r\n\r\nWe welcome contributions! For a complete guide on how to contribute, please see the [developer guide](https://develmusa.github.io/mkdocs-network-graph-plugin/how-to/for-developers/).\r\n\r\nTo get started, set up your environment by following the [Development Installation](#development-installation) instructions. From there, you can run tests and linting using `nox`:\r\n\r\n```bash\r\n# Run tests\r\nuv run nox -s tests\r\n\r\n# Run linting\r\nuv run nox -s lint\r\n```\r\n\r\n### Contribution Guidelines\r\n\r\n- **Bug Reports**: Use the [issue tracker](https://github.com/develmusa/mkdocs-network-graph-plugin/issues)\r\n- **Feature Requests**: Open an issue with your proposal\r\n- **Pull Requests**: Fork, create a feature branch, and submit a PR\r\n- **Documentation**: Help improve our docs\r\n\r\n## License\r\n\r\nThis project is licensed under the **MIT License** - see the [LICENSE](https://github.com/develmusa/mkdocs-network-graph-plugin/blob/main/LICENSE) file for details\r\n\r\n## Acknowledgments\r\n\r\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\r\n- **[Material for MkDocs](https://squidfunk.github.io/mkdocs-material/)**\r\n- **[D3.js](https://d3js.org/)**\r\n- **[MkDocs](https://www.mkdocs.org/)**\r\n\r\n### Related Projects\r\n\r\nExplore other tools with Markdown documentation graph visualization:\r\n\r\n- **[mkdocs-obsidian-interactive-graph-plugin](https://github.com/daxcore/mkdocs-obsidian-interactive-graph-plugin)**\r\n- **[Digital Garden](https://dg-docs.ole.dev/)** - A comprehensive digital garden solution with graph visualization\r\n- **[Foam](https://foambubble.github.io/foam/user/features/graph-visualization.html)** - Personal knowledge management and sharing system with graph features\r\n\r\n---\r\n\r\n\u003cdiv align=\"center\"\u003e\r\n\r\n**[Star this project](https://github.com/develmusa/mkdocs-network-graph-plugin)** if you find it useful!\r\n\r\nMade with AI and ❤️ by [develmusa](https://github.com/develmusa)\r\n\r\n\u003c/div\u003e\r\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fdevelmusa%2Fmkdocs-network-graph-plugin","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fdevelmusa%2Fmkdocs-network-graph-plugin","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fdevelmusa%2Fmkdocs-network-graph-plugin/lists"}