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 --clean
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 filies 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 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.
PyPI
If you maintain a Python project which is hosted on the Python Package Index (PyPI), you can use the hosting provided at pythonhosted.org to host documentation for your project. Run the following commands from your project's root directory to upload your documentation:
mkdocs build --clean
python setup.py upload_docs --upload-dir=site
You documentation will be hosted at http://pythonhosted.org/<projectname>/
where <projectname>
is the name you used to register your project with PyPI.
There are a few prerequisites for the above to work:
- You must be using Setuptools in your
setup.py
script (Distutils does not offer anupload_docs
command). - Your project must already be registered with PyPI (use
python setup.py register
). - Your
mkdocs.yml
config file and your "docs" directory (value assigned to the docs_dir configuration option) are presumed to be in the root directory of your project alongside yoursetup.py
script. - It is assumed that the default value (
"site"
) is assigned to the site_dir configuration option in yourmkdocs.yaml
config file. If you have set a different value, assign that value to the--upload-dir
option.
Other Providers
Any hosting provider which can serve static files can be used to serve documentation generated by MkDocs. While is would be imposable 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 connects 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 --clean
scp -r ./site usr@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".