backstage / backstage/mkdocs-monorepo-plugin

File not found error for symbolic links in included docs/ folders

Open
#145 1 comment 0 reactions 0 assignees View on GitHub
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

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

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.