Commit a43163fc authored by Waylan Limberg's avatar Waylan Limberg
Browse files

Document deploying to GH User/Org Pages.

Fixes #1291 and made possable by the work in #1376.
parent d5046892
......@@ -7,17 +7,25 @@ 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
[GitHub Pages] to host the documentation for your project. There are two basic
types of GitHub Pages sites: [Project Pages] sites, and [User and Organization
Pages] sites. They are nearly identical but have some important differences,
which require a different work flow when deploying.
### Project Pages
Project Pages sites are simpler as the site files get deployed to a branch
within the project repository (`gh-pages` by default). 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:
```sh
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.
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.
......@@ -29,12 +37,56 @@ 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.
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.
### Organization and User Pages
User and Organization Pages sites are not tied to a specific project, and the
site files are deployed to the `master` branch in a dedicated repository named
with the GitHub account name. Therefore, you need working copies of two
repositories on our local system. For example, consider the following file
structure:
```no-highlight
my-project/
mkdocs.yml
docs/
orgname.github.io/
```
After making and verifying updates to your project you need to change
directories to the `orgname.github.io` repository and call the
`mkdocs gh-deploy` command from there:
```sh
cd ../orgname.github.io/
mkdocs gh-deploy --config-file ../my-project/mkdocs.yml --remote-branch master
```
Note that you need to explicitly point to the `mkdocs.yml` configuration file as
it is no longer in the current working directory. You also need to inform the
deploy script to commit to the `master` branch. You may override the default
with the [remote_branch] configuration setting, but if you forget to change
directories before running the deploy script, it will commit to the `master`
branch of your project, which you probably don't want.
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 pages repository by hand if you're
using the `gh-deploy` command because you will lose your work.
[GitHub]: https://github.com/
[GitHub Pages]: https://pages.github.com/
[Project Pages]: https://help.github.com/articles/user-organization-and-project-pages/#project-pages-sites
[User and Organization Pages]: https://help.github.com/articles/user-organization-and-project-pages/#user-and-organization-pages-sites
[ghp-import]: https://github.com/davisp/ghp-import
[remote_branch]: ./configuration.md#remote_branch
## Read the Docs
......
Markdown is supported
0% or .
You are about to add 0 people to the discussion. Proceed with caution.
Finish editing this message first!
Please register or to comment