Where Does MkDocs Store Config and Output?
MkDocs reads mkdocs.yml at your project root and writes the built docs to site, with the source pages in docs by default.
Last updated
MkDocs projects are refreshingly legible on disk. One YAML file at the root (mkdocs.yml) declares the site name, theme, plugins, and navigation. The docs folder holds Markdown pages that mirror the nav. The docs_dir setting can relocate that folder, but the default docs beside mkdocs.yml is what nearly every project uses. Everything else is generated.
The site folder is the build output that mkdocs build produces and mkdocs gh-deploy pushes. It regenerates completely, so treat it as disposable. Plugin caches occasionally hide beside it, but the config plus docs folder is the whole source of truth.
Where MkDocs stores this, by platform
[ProjectDir]\mkdocs.yml
Site name, theme, plugins, and nav. Material for MkDocs adds its own section here rather than a second file. Keep it versioned; it is the heart of the project.
[ProjectDir]/mkdocs.yml
Same in-folder layout on macOS. Python environments (venv, pipx, system) change where mkdocs runs from, never where the project files live.
[ProjectDir]/mkdocs.yml
Same arrangement. The site output folder regenerates fully, so back up mkdocs.yml and docs rather than built HTML.
Frequently asked questions
Built docs look outdated. What do I remove?
Delete the site folder and run mkdocs build again. It is pure output, so wiping it fixes stale pages without touching a single source file.
Should the site folder be committed?
Yes. Commit mkdocs.yml, the docs folder, and any custom theme or plugin config. The site folder regenerates on every build and belongs in .gitignore.
Notice an outdated path? Let us know.