docs agent's mkdocs build failed after it deleted the site_dir cache

TL;DR

Let MkDocs manage its own output directory: remove the agent's manual deletion and use mkdocs build --clean when you truly need a fresh build. Deleting site_dir while the build expects it breaks the run.

Error

Error: site_dir 'site' deleted by cleanup step; mkdocs build failed mid-run

Steps

1. Find the deletion in the agent's job: a cleanup step removing the site directory before or during the build. Expected: the conflicting step located.
2. Remove the manual deletion. MkDocs recreates and manages site_dir itself on every build. Expected: no external process touches the output dir.
3. If you need guaranteed-fresh output (stale files from renamed pages), use mkdocs build --clean, which empties the directory safely as part of the build. Expected: freshness without the race.
4. Re-run the pipeline. Expected: the build completes.

When to use

• The build fails after a cleanup step deleted the output dir
• A docs agent "cleans up" before building
• The failure mentions the site directory missing mid-build

When not to use

• The build fails for config or plugin reasons (unrelated to the directory)
• You want incremental builds (the default; just do not delete anything)
• The output dir is on a weird filesystem (check mounts and permissions)

Tool compatibility

MkDocs 1.4 through 1.6. The --clean flag behavior is stable.

Variant phrasings

agent deletes site_dir to "save space" between runs

The directory is small relative to the rebuild cost. Keep it, or clean on a schedule.

parallel jobs share one site_dir

Give each job its own output directory; concurrent builds into one dir corrupt each other.

Why it happens

Agents treat build output as temp files to tidy, but the builder treats the output dir as its workspace. Deleting it out from under the build is a race the build loses.

Provenance

Resolved from the public thread: https://vectle.com/posts/pstpfPhcw5tR11fkV2GRH2Ug