backstage / backstage/mkdocs-monorepo-plugin

Windows build fails when using slashes in site_name

Open Beginner friendly
#143 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 have a monorepo setup. Since I have quite a lot of packages the documentation started to get messy and I wanted to break it down a bit more. This is how in a submodule the mkdocs.yml looks like:

```yml
site_name: instruments/midas-adam-switch
```
This works without problems on linux systems, however we also have devs on windows and there it seems the slash is causing problems:

```sh
ERROR - Error reading page 'instruments/midas-adam-switch/api/adam.md': join() missing 1 required positional argument: 'path'
Traceback (most recent call last):
...
File "C:\Users\rubigi\git\midas\.venv\lib\site-packages\mkdocs_monorepo_plugin\edit_uri.py", line 39, in __get_page_dir_alias
alias = path.join(*parts)
TypeError: join() missing 1 required positional argument: 'path'
```
So the error originates from [here](https://github.com/backstage/mkdocs-monorepo-plugin/blob/f62ae22e387c1cb2ef358a0a74926400d3d8021f/mkdocs_monorepo_plugin/edit_uri.py#L33).

I added some print statements to the file in my venv to have some example output:

```py
def __get_page_dir_alias(self):
parts = self.page.url.split("/")
print(f'{self.plugin.aliases.keys()=}')
while True:
print(f'{parts=}')
parts.pop()
alias = path.join(*parts)
print(f'{alias=}')
if alias in self.plugin.aliases:
return alias
```

Which outputs:

```
self.plugin.aliases.keys()=dict_keys(['instruments/midas-adam-switch'])
parts=['instruments', 'midas-adam-switch', 'api', 'adam', '']
alias='instruments\\midas-adam-switch\\api\\adam'
parts=['instruments', 'midas-adam-switch', 'api', 'adam']
alias='instruments\\midas-adam-switch\\api'
parts=['instruments', 'midas-adam-switch', 'api']
alias='instruments\\midas-adam-switch'
parts=['instruments', 'midas-adam-switch']
alias='instruments'
parts=['instruments']
```

The fix is actually quite simple, normalize the windows backslashes:

```py
def __get_page_dir_alias(self):
parts = self.page.url.split("/")
while True:
parts.pop()
alias = path.join(*parts).replace("\\", "/")
if alias in self.plugin.aliases:
return alias
```

Which fixes the pathing on windows. I tested the fix on both linux and windows and it worked for me in both cases. I would be willing to open a pr to address this, but wanted to create an issue first to discuss 😄

Contributor guide

Open the contributing guide

Research direction

Start in mkdocs_monorepo_plugin/edit_uri.py at __get_page_dir_alias and reproduce the reported site_name case on Windows and Linux. Verify that aliases containing slashes are found consistently and that the documented monorepo build completes without the join() error.

Written by the indexing model from the issue text.

Assessment

Tech stack
python
Domain
documentation
Issue type
Bug
Difficulty
2/5
Estimated time
1-3 hours
Activity status
Stale
Clarity
Clearly specified
Newbie friendliness
72/100

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.