backstage / backstage/mkdocs-monorepo-plugin
File not found error for symbolic links in included docs/ folders
- Dominant language
- Python
- Stars
- 400
- Forks
- 80
- PR merge metrics
- No merged PRs in 30d
Description
I tried including a "mkdocs.yml" in a submodule which has a symbolic link in its `docs/` folder for a `Contributing.md` file which is just a symbolic like to `../CONTRIBUTING.md` (and hence outside of the included `docs/` folder).
When trying to build the docs, I get an ERROR: `ERROR - File not found: /Contributing.md`
The end of the traceback looks like (names in angle brackes <> are redactions to remove PII):
```sh
File "./.venv/lib/python3.13/site-packages/mkdocs_enumerate_headings_plugin/plugin.py", line 110, in on_nav
page.read_source(config)
~~~~~~~~~~~~~~~~^^^^^^^^
File "/.venv/lib/python3.13/site-packages/mkdocs/structure/pages.py", line 212, in read_source
source = self.file.content_string
^^^^^^^^^^^^^^^^^^^^^^^^
File "/.venv/lib/python3.13/site-packages/mkdocs/structure/files.py", line 461, in content_string
with open(self.abs_src_path, encoding='utf-8-sig', errors='strict') as f:
~~~~^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
FileNotFoundError: [Errno 2] No such file or directory: '/tmp/docs_4ef_b3l1//Contributing.md'
```
From what I can gather, you are copying the symlink to the temporary directory you merge everything into, but you are **NOT** copying the file it links to and hence will get a `FileNotFoundError` exception. You either need to copy the contents and create a real file instead of a symlink or also copy the linked file.
I suspect this may essentially be a duplicate of #144 , but hopefully if you can combine the info present in both it should make it easier to diagnose and fix.
Contributor guide
Research direction
Reproduce the build with a submodule whose docs/ folder contains a symlink to a file outside that folder, then inspect the temporary merged tree and the symlink handling around the MkDocs plugin traceback. Confirm the expected behavior for the linked file and verify that the build no longer raises FileNotFoundError.
Written by the indexing model from the issue text.
Assessment
- Tech stack
- python
- Domain
- documentation
- Issue type
- Bug
- Difficulty
- 4/5
- Estimated time
- 3-5 days
- Activity status
- Stale
- Clarity
- Mostly clear
- Newbie friendliness
- 38/100