"Build Documentation" Workflow cannot find module material.extensions

[mrschick]

Context

I am trying to run Materials for MkDocs on a private repo, only issue is that the "Build Documentation" Workflow, which I would like to keep using for future internal PR validation, keeps failing for odd reasons.
At first I thought it was a config issue on my end, but it turns out even unmodified forks of the repo present the issue.

Bug description

When forking squidfunk/mkdocs-material, the workflow "Build Documentation" will always fail with the following error:
https://github.com/mrschick/mkdocs-material-fork/actions/runs/10848399089/job/30105429423

Run mkdocs build --clean
Error: MkDocs encountered an error parsing the configuration file: while constructing a Python object
cannot find module 'material.extensions.emoji' (No module named 'material.extensions')
  in "/home/runner/work/mkdocs-material-fork/mkdocs-material-fork/mkdocs.yml", line 144, column 24
Error: Process completed with exit code 1.

When running mkdocs build --clean in a local clone of the same forked repo, both with Windows 10 and WSL2 (running Ubuntu-22.04), no errors are thrown and site is built correctly.
Removing the affected markdown_extensions: from mkdocs.yaml only serves to throw a different error on some other extension.

Related links

• Reporting a bug

Reproduction

No minimal reproduction available, issue reproduction requires running Workflows on an unmodified Fork of squidfunk/mkdocs-material.

Steps to reproduce

1. Make a fork of squidfunk/mkdocs-material;
2. Enable Workflows via the Fork's "Actions" tab;
3. Push an empty commit or a valid documentation change, in order to trigger Workflow execution;
4. The "Build Documentation" Workflow will fail;

Browser

No response

Before submitting

• I have read and followed the bug reporting guidelines.
• I have attached links to the documentation, and possibly related issues and discussions.
• I assure that I have removed all customizations before submitting this bug report.
• I have attached a .zip file with a minimal reproduction using the built-in info plugin.

[kamilkrzyskow]

Hello @mrschick,
I tested it on my fork and got the same results:

• https://github.com/kamilkrzyskow/mkdocs-material/actions/runs/10849879693/job/30110032554

It turns out that import material (and this happens when MkDocs loads the theme) loads the material directory as the material module. And because of the sparse-checkout the initial checkout doesn't include the full material directory and therefore it doesn't work on forks.

mkdocs-material/.github/workflows/documentation.yml

Lines 45 to 49 in 8df393d

	sparse-checkout: |
	docs
	includes
	material/overrides
	src/templates/partials/languages

It works in the mkdocs-material repository, because it fetches the whole Insiders material directory and overrides it later.

mkdocs-material/.github/workflows/documentation.yml

Lines 89 to 90 in 8df393d

	rm -rf material
	cp -r mkdocs-material-insiders/material material

---

My suggestion would be to use the recommended publishing workflow:

• https://squidfunk.github.io/mkdocs-material/publishing-your-site/

as the workflow from the repository has more of such "hacks" that shouldn't be copied "just because" it's used here.

Note

In the coming days I'm planning to make a PR with cache handling updates for the publishing guide workflow, so please keep in mind that it will be updated.

[mrschick]

Thanks, that finally cleared it up 👌🏻

Since I don't plan on deploying through pages, I didn't consider using that guide's workflow as a base.

[squidfunk]

Converting to discussion.