Project sites using MKDocs
MKDocs is a static site generator designed for creating project documentation. However, at least one ASF project uses it to build their entire project website.
To build a project website, you need to use a special MKDocs build command sequence so it can handle the project site's .asf.yaml file, which must be in the root of the site.
Do not use the command mkdocs gh-deploy, which removes the site, rebuilds it, and then deploys the updated contents to the given remote branch. This removes, but does not replace, the .asf.yaml file.
Instead, to avoid losing the .asf.yaml file, use this build command sequence:
rm -r site
mkdir site
cp ../.asf.yaml site/
mkdocs gh-deploy --dirty
Copyright 2026, The Apache Software Foundation, Licensed under the Apache License, Version 2.0.
Apache® and the Apache logo are trademarks of The Apache Software Foundation.