backstage / backstage/mkdocs-monorepo-plugin

[feature] Support for mono-repo that use symlinks

Open
#121 0 comments 1 reaction 0 assignees View on GitHub
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

Open the contributing 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

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.