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

[tleonhardt]

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: <path>/Contributing.md

The end of the traceback looks like (names in angle brackes <> are redactions to remove PII):

  File ".<path>/.venv/lib/python3.13/site-packages/mkdocs_enumerate_headings_plugin/plugin.py", line 110, in on_nav
    page.read_source(config)
    ~~~~~~~~~~~~~~~~^^^^^^^^
  File "<path>/.venv/lib/python3.13/site-packages/mkdocs/structure/pages.py", line 212, in read_source
    source = self.file.content_string
             ^^^^^^^^^^^^^^^^^^^^^^^^
  File "<path>/.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/<nav_name>/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.

[bluegreyshoes]

I think this is due to the change made in #122.

That PR mentions putting the breaking change behind a feature flag, which would be a good idea.