landmaj / mkdocs-d2-plugin Goto Github PK

View Code? Open in Web Editor NEW

21.0 21.0 4.0 279 KB

A plugin for embedding D2 diagrams in MkDocs.

Home Page: https://landmaj.github.io/mkdocs-d2-plugin/

License: MIT License

Python 90.86% Makefile 0.91% Nix 6.59% Shell 0.48% CSS 1.18%

diagrams mkdocs mkdocs-plugin text-to-diagram

mkdocs-d2-plugin's People

Contributors

Stargazers

Watchers

Forkers

karreg kennysliding ss185994 kevgliss

mkdocs-d2-plugin's Issues

go installed d2 version

previously (v1.1.0) worked but now I get this error:

 ...
  File "/home/scott/.cache/bazel/_bazel_scott/a6c0cae1c499521202c68dd96735be2b/execroot/_main/bazel-out/k8-fastbuild/bin/docs/mkdocs.runfiles/pip_mkdocs_d2_plugin/site-packages/d2/plugin.py", line 42, in on_config
    d2_version = version.parse(result.stdout.decode().strip())
                 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
  File "/home/scott/.cache/bazel/_bazel_scott/a6c0cae1c499521202c68dd96735be2b/execroot/_main/bazel-out/k8-fastbuild/bin/docs/mkdocs.runfiles/pip_packaging/site-packages/packaging/version.py", line 52, in parse
    return Version(version)
           ^^^^^^^^^^^^^^^^
  File "/home/scott/.cache/bazel/_bazel_scott/a6c0cae1c499521202c68dd96735be2b/execroot/_main/bazel-out/k8-fastbuild/bin/docs/mkdocs.runfiles/pip_packaging/site-packages/packaging/version.py", line 198, in __init__
    raise InvalidVersion(f"Invalid version: '{version}'")
packaging.version.InvalidVersion: Invalid version: 'v0.6.3-HEAD'

Looks like this section was recently updated:

mkdocs-d2-plugin/d2/plugin.py

Line 42 in 74aa773

d2_version = version.parse(result.stdout.decode().strip())

Error after enable in mkdocs

Hello!
Installed the plugin, but I get an error when running mkdocs.

INFO    -  mkdocs-d2-plugin: Using cache at .cache/plugin/d2/db (None)
Traceback (most recent call last):
  File "/usr/local/lib/python3.11/site-packages/mkdocs/livereload/__init__.py", line 211, in _build_loop
    self.builder()
  File "/usr/local/lib/python3.11/site-packages/mkdocs/commands/serve.py", line 67, in builder
    build(config, serve_url=None if is_clean else serve_url, dirty=is_dirty)
  File "/usr/local/lib/python3.11/site-packages/mkdocs/commands/build.py", line 265, in build
    config = config.plugins.on_config(config)
             ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
  File "/usr/local/lib/python3.11/site-packages/mkdocs/plugins.py", line 587, in on_config
    return self.run_event('config', config)
           ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
  File "/usr/local/lib/python3.11/site-packages/mkdocs/plugins.py", line 566, in run_event
    result = method(item, **kwargs)
             ^^^^^^^^^^^^^^^^^^^^^^
  File "/usr/local/lib/python3.11/site-packages/d2/plugin.py", line 44, in on_config
    d2_version = version.parse(raw_version)
                 ^^^^^^^^^^^^^^^^^^^^^^^^^^
  File "/usr/local/lib/python3.11/site-packages/packaging/version.py", line 54, in parse
    return Version(version)
           ^^^^^^^^^^^^^^^^
  File "/usr/local/lib/python3.11/site-packages/packaging/version.py", line 200, in __init__
    raise InvalidVersion(f"Invalid version: '{version}'")
packaging.version.InvalidVersion: Invalid version: ''

If I silence the error through an obsolete package packaging==21.3, it works fine

> pip list

annotated-types        0.7.0
beautifulsoup4         4.12.3
certifi                2024.2.2
charset-normalizer     3.3.2
click                  8.1.7
d2                     0.7
EditorConfig           0.12.4
ghp-import             2.1.0
idna                   3.7
Jinja2                 3.1.4
jsbeautifier           1.15.1
Markdown               3.6
MarkupSafe             2.1.5
mergedeep              1.3.4
mkdocs                 1.6.0
mkdocs-d2-plugin       1.3.3
mkdocs-get-deps        0.2.0
mkdocs-mermaid2-plugin 1.1.1
packaging              21.3
pathspec               0.12.1
pip                    24.0
platformdirs           4.2.2
pydantic               2.7.1
pydantic_core          2.18.2
pymdown-extensions     10.8.1
pyparsing              3.1.2
python-dateutil        2.9.0.post0
PyYAML                 6.0.1
pyyaml_env_tag         0.1
requests               2.32.2
setuptools             65.5.1
six                    1.16.0
soupsieve              2.5
tabulate               0.9.0
typing_extensions      4.11.0
urllib3                2.2.1
watchdog               4.0.0
wheel                  0.43.0

File not found errors caused by blog plugin

Material for MkDocs blog plugin copies markdown files to create excerpts but it does not copy assets alongside them. This causes "file not found" errors.

For context: #11

Handle multiboard diagrams

Composition is currently not supported due to D2 limitiation:

err: failed to compile test.d2: multiboard output cannot be written to stdout

There is this comment in D2 source code but no related issue, so chances are this will not be fixed in a near future.

It doesn't allow outputting to stdout because such diagrams produce multiple files. I can either fix this in D2 or figure out how to embed such diagrams in HTML and use a temporary file for rendering.

Light/Dark palette switching with mkdocs's palette toggle

Hello,

Currently, d2 only switches the theme in accordance with system/browser preference.

Is there a way to sync the theme with mkdocs's current palette instead?

Minimal reproduction for test:

9.5.25+insiders.4.53.11-d2-does-not-respect-mkdocs-palette-toggle.zip

P.S. Basic function works great! Thank you for your work on this plugin.

fence.py has a bug?

I am working under Windows 10, and has installed D2. D2's version is 0.6.5

Python's version is 3.8.10 32bit.

when i start mkdocs server with 'python -m mkdocs serve', some error happened.

Handle .d2 files

Hello,

I'm currently (and freshly) evaluating d2 as a replacement for drawio in our mkdocs documentations, as drawio is a bit overkill, and d2 looks promising, especially since I prefer the -as-code logic.

Your plugin is working fine, and many thanks for that!

Still, I would be glad to see this plugin handle .d2 files, alongside d2 markdown blocks. I have multiple reasons for that:

the diagram may be used as a standalone diagram. As markdown block, it requires all the mkdocs galaxy to get the generated diagram
people working on the diagram may be different than people working on the documentation
a diagram could be included in multiples places

As example, I'm using the mkdocs drawio plugin that does exactly that. Of course there's a technical reason, drawio only handling its own format, but in the end it has been proven more effective than embedded diagram.

I have a sample mkdocs site, alongside an mkdocs devcontainer publicly available. I would be glad to discuss this need with you, if you are interested.

Thanks!

Imports don't work

For example, given this structure:

./src/_styles.d2

  style: {
    fill: "#f9f9f9"
    stroke: "#f9f9f9"
  }

./src/test.d2

...@_styles # Importing styles

test: {
  a -> b
}

When rendering the test.d2 file using:
![Diagram](./src/test.d2)

I see this error in the logs (and obviously no image is generated as a result)

| ERROR   -  mkdocs-d2-plugin: err: failed to compile -: -:1:1: failed to import "_styles.d2": open _styles.d2: no such file or directory

I am able to generate the image correctly using the command line (both svg and png)

d2 -l elk -s ./src/test.d2 test.svg

Cache generated files to speed up generation

Diagram generation can be slow, depending on the diagrams complexity. Especially with the ELK layout engine.

For example, with a simple markdown documentation:

generation will take 0.61 seconds with no d2 diagrams
generation will take 7 seconds with the following diagram included twice (embedded and included):
```
direction: right
🧔‍♂️ -> 🌍: 👋
```

(values depending on external factors, but magnitude orders are about the same)

When writing a documentation with mkdocs, the best option is to use mkdocs serve that will rebuild the documentation when the source is changed. In this case, mkdocs-d2-plugin will re-generate all diagrams, even though the source file is not updated.

A cache system, allowing to rebuild diagrams only when the source file has been changed would be great. drawio exporter plugin has such an feature for the same reason (especially since drawio requires chrome to generate images).

Grid support

I can't seem to get grids to work, is there any plan to add support?

landmaj / mkdocs-d2-plugin Goto Github PK

mkdocs-d2-plugin's People

Contributors

Stargazers

Watchers

Forkers

mkdocs-d2-plugin's Issues

go installed d2 version

Error after enable in mkdocs

File not found errors caused by blog plugin

Handle multiboard diagrams

Light/Dark palette switching with mkdocs's palette toggle

fence.py has a bug?

Handle .d2 files

Imports don't work

Cache generated files to speed up generation

Grid support

Recommend Projects

React

Vue.js

Typescript

TensorFlow

Django

Laravel

D3

Recommend Topics

javascript

web

server

Machine learning

Visualization

Game

Recommend Org

Facebook

Microsoft

Google

Alibaba

D3

Tencent