Skip to content

Skip missing static files instead of aborting the build - #4211

Open
official-burak wants to merge 2 commits into
mkdocs:masterfrom
official-burak:fix/skip-missing-static-copy
Open

Skip missing static files instead of aborting the build#4211
official-burak wants to merge 2 commits into
mkdocs:masterfrom
official-burak:fix/skip-missing-static-copy

Conversation

@official-burak

@official-burak official-burak commented Aug 19, 2026

Copy link
Copy Markdown

Fixes #4048.

File.copy_file currently lets shutil.copyfile raise FileNotFoundError for a dangling symlink or a source that disappeared after discovery. That aborts mkdocs build / mkdocs serve even with strict: false.

This catches the missing source, logs a warning, and continues. is_modified() also treats an unreadable source as modified so a dirty rebuild takes the same warning path instead of crashing on os.path.getmtime.

Tests cover a dangling symlink, a deleted source file, and a dirty rebuild that already has a destination copy.

@official-burak
official-burak force-pushed the fix/skip-missing-static-copy branch 2 times, most recently from b1bbf18 to e5dcc9b Compare August 19, 2026 18:44
Dangling symlinks and files that vanish after discovery currently raise
FileNotFoundError from copy_file and crash mkdocs build/serve. Warn and
continue so a broken media link cannot take down the whole site.
@official-burak
official-burak force-pushed the fix/skip-missing-static-copy branch from e5dcc9b to e2ea187 Compare August 19, 2026 18:45
pathspec 1.x keeps leading whitespace (git-compatible). The user-guide
fixture was indented like Python source, so *_unpublished.md never matched
and CI aborted on Python versions that install pathspec>=1.
@official-burak

Copy link
Copy Markdown
Author

test (3.11, ubuntu-latest) (and the other 3.10+/pypy jobs that actually created a hatch test env) failed on test_draft_docs_with_comments_from_user_guide, not on the new static-copy tests.

The static-copy change is unrelated. CI installs pathspec>=0.11.1; Python 3.9+ gets pathspec 1.x, which keeps leading whitespace (git-compatible). The user-guide fixture was indented like Python source, so *_unpublished.md never matched and draft pages were written into site_dir. Python 3.8 still installs pathspec 0.12.1, which stripped those spaces, which is why that job stayed green.

Pushed 67ac6c3: textwrap.dedent() the fixture. Locally, with pathspec 1.1.1:

python -m unittest mkdocs.tests.build_tests.BuildTests.test_draft_docs_with_comments_from_user_guide
mkdocs.tests.structure.file_tests.TestFiles.test_copy_file_dangling_symlink
mkdocs.tests.structure.file_tests.TestFiles.test_copy_file_missing_source
mkdocs.tests.structure.file_tests.TestFiles.test_copy_file_dangling_symlink_dirty
# OK

@official-burak

Copy link
Copy Markdown
Author

Follow-up: test (3.11, ubuntu-latest) is green on 67ac6c3 (728 tests). Remaining red cells on this SHA fail before unittest:

  • pypy ubuntu: hatch extra cryptography failed to build a wheel (maturin)
  • pypy windows: hatch extra zstandard failed (No module named distutils.msvc9compiler)
  • macOS 3.10: ValueError: Unknown environment collector: mkdocs while installing hatch

Those are hatch/native-dep install failures, not the static-copy change.

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

BUG - Dangling symlink crashes build

1 participant