Skip to content

README.md

Latest commit

 

History

History
76 lines (60 loc) · 4.29 KB

README.md

File metadata and controls

76 lines (60 loc) · 4.29 KB

Interactive Graph for Material for MkDocs

Plugin for Material for MkDocs to draw an interactive graph like Obsidian. The graph inside the sidebar is just available for non-mobile website. The modal view via the button next to the light/dark mode switch shall work on all devices.

Refer Github Pages for a demonstration of the interactive graph in Material for MkDocs.

Build Status PyPI Version PyPi Downloads GitHub License

Installation

Available on PyPI. Install via pip install mkdocs-obsidian-interactive-graph-plugin or add it to your requirements.txt.

Usage

Setup in MkDocs

Activate the plugin in mkdocs.yml, but note that this plugin has to be located before plugins, that replace wikilinks by markdown links. Currently just wikilinks like [[Link#Anchor|Custom Text]] are supported.

plugins:
  - obsidian-interactive-graph

extra_javascript:
  - https://fastly.jsdelivr.net/npm/jquery/dist/jquery.min.js
  - https://fastly.jsdelivr.net/npm/echarts/dist/echarts.min.js
  - assets/javascripts/interactive_graph.js

extra_css:
  - assets/stylesheets/interactive_graph.css

Graph Javascript by Apache ECharts

A interactive_graph.js example can be downloaded from here and must be located into the docs directory under docs/YourSiteName/assets/javascripts/interactive_graph.js.

Beginning from version 0.3.0 the default graph inside the sidebar was minimized to edges related to the current page only. The previous behavior can be restored by setting global to true at line draw_graph_sidebar(myChart, global=false) at top of javascript file.

Development

Testing

To contribute to the project, please ensure all tests pass. We use pytest for unit and integration testing.

  1. Install Dependencies: Install the package in editable mode along with testing requirements:

    pip install -e .
pip install pytest pytest-benchmark

  2. Run Tests: Run the full suite from the root directory:

    pytest

    You can also run specific categories of tests:

    # Run only integration tests (full build cycle)
pytest tests/test_integration.py

# Benchmark performance
pytest tests/test_performance.py

Docker

Adapt the .env and mkdocs.yml files to your needs. DEV=ON will rebuild the mkdocs-obsidian-interactive-graph-plugin from local files. If DEV != ON the upstream packages of PyPI will be used. Build and start the Docker container via docker compose up --build [-d].

Limitations

There is a bug in ECharts library in pinch to zoom feature (apache/echarts#21068), but it seems like they will not fix it. Anybody can fix it by its own, by downloading the current version of the javascript library and patching via diff of the pull-request and use this in the mkdocs configuration. May another good idea could be, to not use the ECharts library... There is another project like this, that uses D3 library instead of ECharts: https://github.com/develmusa/mkdocs-network-graph-plugin including some more improvements.

References