jdoiro3 / mkdocs-multirepo-plugin

Build documentation in multiple repos into one site.
MIT License
135 stars 47 forks source link

Symlinks from docs dir to toplevel project dir do not work #57

Open hjoukl opened 2 years ago

hjoukl commented 2 years ago

Hi,

nice plugin!

Suppose you have a repo myrepowith toplevel LICENSE and AUTHORS documents that are symlinked from the docs folder, to avoid duplication but use this info in the mkdocs-generated documentation:

AUTHORS.md
LICENSE.md
docs
├── about
│   ├── AUTHORS.md -> ../../AUTHORS.md
│   └── LICENSE.md -> ../../LICENSE.md
├── index.md
mkdocs.yml

This works with mkdocs serve|build when the repo is used "standalone".

However, if you want such a repo to be imported with multirepo-plugin:

# mkdocs.yml of the importing repo
nav:
  - Home: index.md
  - Documentation:
    - myrepo: '!import https://vcs.example.org/user/myrepo?branch=feature/great-improvements&docs_dir=docs&multi_docs=False&config=mkdocs.yml&extra_imports=["AUTHORS.md", "LICENSE.md"]'

... the symlinks get broken in the temp_dir sparse checkout:

$ tree temp_dir/
temp_dir/
└── documentation
    └── myrepo
        ├── about
        │   ├── AUTHORS.md -> ../../AUTHORS.md
        │   └── LICENSE.md -> ../../LICENSE.md
        ├── AUTHORS.md
        ├── index.md
        ├── LICENSE.md
        ├── mkdocs.yml

This is due to the way the docs folders contents are put into temp_dir/documentation/myrepo directly, which changes the nesting level. This makes the symlinks invalid.

Making the links the other way round (e.g. `AUTHORS.md --> docs/about/AUTHORS.md) isn't attractive since you lose the ability to directly render the markdown files in the VCS-GUI (at least in bitbucket, in my case), since the actual git repository content of such symlinks is the path to the symlinked file.

And you also can't just reference a markdown file in nav: ...outside of the docs_dir.

Workaround: Duplicate files. Avoid links crossing docs_dir.

Best regards, Holger

ssbarnea commented 1 year ago

It took me more than an hour of debugging to discover the same bug. In my case I symlink the index.md to ../README.md.

mkdocs has no problem build and service the docs, only multirepo fails.

It work mentioning that I cannot reverse the files as github UI does not recognize README.md files in repository root.