backstage / backstage/mkdocs-monorepo-plugin

Can you make the monorepo plugin compatible with the mkdocs D2 plugin?

Open
#131 0 comments 0 reactions 0 assignees View on GitHub
Dominant language
Python
Stars
400
Forks
80
PR merge metrics
No merged PRs in 30d

Description

I'm trying to integrate docs that use the [mkdocs-d2-plugin](https://pypi.org/project/mkdocs-d2-plugin/0.4.1/) into a Backstage Techdocs docs site. Could you look into the errors and see if it's possible to make these packages compatible?

When I attempt to install mkdocs, [mkdocs-d2-plugin](https://pypi.org/project/mkdocs-d2-plugin/0.4.1/) and [mkdocs-monorepo-plugin](https://github.com/backstage/mkdocs-monorepo-plugin) using [poetry](https://python-poetry.org/), I get a version solving error:

```
joseph.leiber % poetry add mkdocs mkdocs-techdocs-core mkdocs-d2-plugin
Using version ^1.6.0 for mkdocs
Using version ^1.3.5 for mkdocs-techdocs-core
Using version ^1.3.4 for mkdocs-d2-plugin

Updating dependencies
Resolving dependencies... (0.2s)

Because no versions of mkdocs-techdocs-core match >1.3.5,<2.0.0
and mkdocs-techdocs-core (1.3.5) depends on mkdocs-material (9.5.13), mkdocs-techdocs-core (>=1.3.5,<2.0.0) requires mkdocs-material (9.5.13).
And because mkdocs-material (9.5.13) depends on mkdocs (>=1.5.3,<1.6.0), mkdocs-techdocs-core (>=1.3.5,<2.0.0) requires mkdocs (>=1.5.3,<1.6.0).
So, because minimal depends on both mkdocs (^1.6.0) and mkdocs-techdocs-core (^1.3.5), version solving failed.
```

If I bypass the version solving warning and attempt to install the packages using pip and run `mkdocs serve`, I get an quite lengthy TypeError that seems to be rooted in the monorepo plugin itself, according to Traceback.

Here's the truncated error:

```
INFO - Building documentation...
INFO - mkdocs-d2-plugin: Using cache at .cache/plugin/d2/db (dbm.ndbm)
INFO - Cleaning site directory
ERROR - Error reading page 'index.md': join() missing 1 required positional argument: 'a'
Traceback (most recent call last):
File "/Users/joseph.leiber/Library/Caches/pypoetry/virtualenvs/minimal-sCI7Dks--py3.12/bin/mkdocs", line 8, in
sys.exit(cli())
^^^^^
...
...
...
File "/Users/joseph.leiber/Library/Caches/pypoetry/virtualenvs/minimal-sCI7Dks--py3.12/lib/python3.12/site-packages/mkdocs_monorepo_plugin/edit_uri.py", line 35, in __get_page_dir_alias
alias = path.join(*parts)
^^^^^^^^^^^^^^^^^
TypeError: join() missing 1 required positional argument: 'a'
```

An odd note is that I'm able to run all of this without errors on a GitHub runner, but the D2 plugin fails to generate an SVG - it just renders a fenced D2 codeblock in text. In other words, it just fails silently.

On the runner, I'm using Python 3.11.5, mkdocs-techdocs-core==1.3.5, mkdocs-monorepo-plugin==1.1.0, and the latest mkdocs-d2-plugin.

Contributor guide

Open the contributing guide

Research direction

Start by reproducing the Poetry dependency conflict and the `mkdocs serve` failure with the versions listed in the issue. Read `mkdocs_monorepo_plugin/edit_uri.py`, especially `__get_page_dir_alias`, and compare behavior with the mkdocs-d2-plugin setup. Done means the packages install together and D2 content renders as SVG without the `join()` error.

Written by the indexing model from the issue text.

Assessment

Tech stack
python
Domain
documentation, tooling
Issue type
Bug
Difficulty
4/5
Estimated time
3-5 days
Activity status
Stale
Clarity
Needs clarification
Newbie friendliness
35/100

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.