This PR adds support for mono-repos that uses symlinks to link 'package dependencies'.
The current behaviour of mkdocs-monorepo-plugin is to resolve the !include and *includes folders to the absolute path by using the resolve() path method. The side-effect is though that this method also resolves symlinks, which causes compatibility issues with mono-repos that utilise symlinks to link package dependencies. For example pnpm typescript / javascript mono-repos.
By switching the path .resolve() method to .absolute() the nav paths are still resolved to absolute folders in 'local' context without resolving the symlinks.
This is a small breaking change in the folder resolve behaviour, nav paths are still resolved absolute with the exception that links are not resolved to the final target anymore.
Based on the current plugin setup I expect the impact to be limited. The current plugin version now blocks compilation (given L175) if that final path resolves to a folder outside of the project directory. So I expect in practise a limited number of projects would be using symlinks today. If needed this could be put behind a plugin feature flag though.
Summary
Fixes https://github.com/backstage/mkdocs-monorepo-plugin/issues/121
Details
This PR adds support for mono-repos that uses symlinks to link 'package dependencies'.
The current behaviour of
mkdocs-monorepo-pluginis to resolve the!includeand*includesfolders to the absolute path by using theresolve()path method. The side-effect is though that this method also resolves symlinks, which causes compatibility issues with mono-repos that utilise symlinks to link package dependencies. For examplepnpmtypescript / javascript mono-repos.By switching the path
.resolve()method to.absolute()the nav paths are still resolved to absolute folders in 'local' context without resolving the symlinks.How it was tested
Manual tested using the folder structure as outlined in https://github.com/backstage/mkdocs-monorepo-plugin/issues/121
Impact
This is a small breaking change in the folder resolve behaviour, nav paths are still resolved absolute with the exception that links are not resolved to the final target anymore.
Based on the current plugin setup I expect the impact to be limited. The current plugin version now blocks compilation (given L175) if that final path resolves to a folder outside of the project directory. So I expect in practise a limited number of projects would be using symlinks today. If needed this could be put behind a plugin feature flag though.