backstage / backstage/mkdocs-monorepo-plugin
[feature] Support for mono-repo that use symlinks
- Dominant language
- Python
- Stars
- 400
- Forks
- 80
- PR merge metrics
- No merged PRs in 30d
Description
## Summary
Request to add support for mono-repos that use symlinks
## Details
We are exploring the usage of `mkdocs` for a typescript mono-repo that uses symlinks via `pnpm` package manager to link packages.
An example folder tree structure would be
```
- docs/*.md
- node_modules/{package-name}/mkdocs.yml << {package-name} is a folder symlink
- mkdocs.yml
```
with a mkdocs.yml config:
```
nav:
- Intro: 'index.md'
- Libraries: '*include ./node_modules/*/mkdocs.yml'
```
Unfortunately the above config does not work as mkdocs-monorepo-plugin resolves the symlinks to absolute paths which are outside of the project directory.
I was curious if there is a need to resolve symlinks for the plugin and if the below two `resolve` actions?
https://github.com/backstage/mkdocs-monorepo-plugin/blob/b1965a216af41c7e503753c63551d894fac8399d/mkdocs_monorepo_plugin/parser.py#L56
https://github.com/backstage/mkdocs-monorepo-plugin/blob/b1965a216af41c7e503753c63551d894fac8399d/mkdocs_monorepo_plugin/parser.py#L117
## Proposal
A suggested change proposal would be to update the above path method `.resolve()` to `.absolute()`, which still resolves the absolute path but does not resolve the symlink per https://docs.python.org/3/library/pathlib.html#pathlib.Path.absolute
Contributor guide
Research direction
Start by reading mkdocs_monorepo_plugin/parser.py at the referenced lines and reproduce the documented pnpm symlink tree with the shown mkdocs.yml. Verify whether preserving symlink paths allows the node_modules package mkdocs.yml files to be included without escaping the project directory; done means the example configuration builds successfully.
Written by the indexing model from the issue text.
Assessment
- Tech stack
- python
- Domain
- documentation
- Issue type
- Feature
- Difficulty
- 3/5
- Estimated time
- 1-2 days
- Activity status
- Stale
- Clarity
- Mostly clear
- Newbie friendliness
- 48/100