Unhandled exception when symlinking isn't allowed

[Lars Wilhelmer]

Contribution guidelines

• I've read the contribution guidelines and wholeheartedly agree

I've found a bug and checked that ...

• ... the problem doesn't occur with the mkdocs or readthedocs themes
• ... the problem persists when all overrides are removed, i.e. custom_dir, extra_javascript and extra_css
• ... the documentation does not mention anything about my problem
• ... there are no open or closed issues that are related to my problem

Description

See our discussion here.

In summary, if you're working on a Windows machine where symlinking isn't allowed, include the privacy plugin, have assets that require symlinking, and want to build locally, the following exception will be raised:

File "...\Local\Programs\Python\Python310\lib\site-packages\material\plugins\privacy\plugin.py", line 121, in on_post_page
value.replace(raw, self._fetch(url, page)),
File "...\AppData\Local\Programs\Python\Python310\lib\site-packages\material\plugins\privacy\plugin.py", line 217, in _fetch
os.symlink(os.path.basename(file), path)
OSError: [WinError 1314] A required privilege is not held by the client: 'css.css' -> '.cache\\fonts.googleapis.com/css'
The terminal process "C:\Windows\System32\WindowsPowerShell\v1.0\powershell.exe -Command mkdocs build" terminated with exit code: 1.

I did more research on this, and it seems the edge case is pretty much on our side. Usually, symlinking should be allowed on Windows, even without admin rights. There's a dedicated user right called "Create symbolic links", which apparently our IT department took away from us, God knows why. You can also enable Windows developer mode to allow symlinking. For more information, see here.

So I think all we need here is exception handling and a warning message explaining that symlinking has to be enabled. (Maybe it can also be disabled on Unix? So it could be useful on any OS.).

Expected behaviour

Actual behaviour

Steps to reproduce

Package versions

• Python: 3.10
• MkDocs: 1.3.0
• Material: 8.3.2+insiders.4.17.2

Configuration

-

System information

• Operating system: Windows 10
• Browser: Firefox

[Martin Donath]

As discussed in #4009 (comment), the solution is to just swallow symlinking errors and circumvent caching for the affected external resources. Additionally, we'll print a warning message on plugin initialization when symlinking is not supported.

This is not a bug, but an enhancement to make the privacy plugin work in restricted environments.

[Martin Donath]

Fixed in squidfunk/mkdocs-material-insiders@8330445. We now catch the symbolic link error and just continue. This means that the plugin will re-request each extension-less file once during the build and on subsequent builds.

[Martin Donath]

@wilhelmer did you have a chance to test the latest changes? Happy to wrap up the next release, if it works.

[Lars Wilhelmer]

My Windows colleague says it works! 😄 👍

[Martin Donath]

Perfect, thanks for testing! I'll push something out asap.

[Martin Donath]

Released as part of 8.3.9+insiders-4.19.2.

[Lars Wilhelmer]

@squidfunk Late follow-up: I haven't worked on a Windows PC for a while, but now I see that we're getting thousands (!) of Couldn't create symbolic link for '{file}' warnings during build. This is because the warning is repeated for every page and every linked file.

Could we please issue one single warning during build that symbolic linking isn't supported and files can't be cached?

[Martin Donath]

Sure, could you please create a new issue for that?