mkdocs/docs/user-guide/deploying-your-docs.md

Deploying your docs

A basic guide to deploying your docs to various hosting providers

---

GitHub Pages

If you host the source code for a project on GitHub, you can easily use GitHub Pages to host the documentation for your project. After you checkout the primary working branch (usually master) of the git repository where you maintain the source documentation for your project, run the following command:

mkdocs gh-deploy

That's it! Behind the scenes, MkDocs will build your docs and use the ghp-import tool to commit them to the gh-pages branch and push the gh-pages branch to GitHub.

Use mkdocs gh-deploy --help to get a full list of options available for the gh-deploy command.

Be aware that you will not be able to review the built site before it is pushed to GitHub. Therefore, you may want to verify any changes you make to the docs beforehand by using the build or serve commands and reviewing the built files locally.

!!! warning

You should never edit files in your gh-pages branch by hand if you're using
the `gh-deploy` command because you will lose your work.

Read the Docs

Read the Docs offers free documentation hosting. You can import your docs using any major version control system, including Mercurial, Git, Subversion, and Bazaar. Read the Docs supports MkDocs out-of-the-box. Follow the instructions on their site to arrange the files in your repository properly, create an account and point it at your publicly hosted repository. If properly configured, your documentation will update each time you push commits to your public repository.

!!! note

To benefit from all of the [features] offered by Read the Docs, you will need
to use the [Read the Docs theme][theme] which ships with MkDocs. The various
themes which may be referenced in Read the Docs' documentation are Sphinx
specific themes and will not work with MkDocs.

Other Providers

Any hosting provider which can serve static files can be used to serve documentation generated by MkDocs. While it would be impossible to document how to upload the docs to every hosting provider out there, the following guidelines should provide some general assistance.

When you build your site (using the mkdocs build command), all of the files are written to the directory assigned to the site_dir configuration option (defaults to "site") in your mkdocs.yaml config file. Generally, you will simply need to copy the contents of that directory to the root directory of your hosting provider's server. Depending on your hosting provider's setup, you may need to use a graphical or command line ftp, ssh or scp client to transfer the files.

For example, a typical set of commands from the command line might look something like this:

mkdocs build
scp -r ./site user@host:/path/to/server/root

Of course, you will need to replace user with the username you have with your hosting provider and host with the appropriate domain name. Additionally, you will need to adjust the /path/to/server/root to match the configuration of your hosts' file system.

See your host's documentation for specifics. You will likely want to search their documentation for "ftp" or "uploading site".

404 Pages

When MkDocs builds the documentation it will include a 404.html file in the build directory. This file will be automatically used when deploying to GitHub but only on a custom domain. Other web servers may be configured to use it but the feature won't always be available. See the documentation for your server of choice for more information.