centersl/mkdocs
1
0
Fork 0
mirror of https://github.com/mkdocs/mkdocs.git synced 2026-03-27 09:58:31 +07:00
Code Issues Packages Projects Releases Wiki Activity

Document using custom domains with GitHub Pages.

Browse Source 
Fixes #1496.
This commit is contained in:
Waylan Limberg
2018-05-24 20:58:25 -04:00
parent 34ef3ca6d0
commit 78ee87cc2e
1 changed files with 28 additions and 4 deletions
Download Patch File Download Diff File Expand all files Collapse all files

32
docs/user-guide/deploying-your-docs.md
View File

@@ -37,8 +37,9 @@ 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 pages repository by hand if you're using
the `gh-deploy` command because you will lose your work the next time you
run the command.
### Organization and User Pages
@@ -78,8 +79,27 @@ 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.
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 the next time you
run the command.
### Custom Domains
GitHub Pages includes support for using a [Custom Domain] for your site. In
addition to the steps documented by GitHub, you need to take one additional step
so that MkDocs will work with your custom domain. You need to add a `CNAME` file
to the root of your [docs_dir]. The file must contain a single bare domain or
subdomain on a single line (see MkDocs' own [CNAME file] as an example). You may
create the file manually, or use GitHub's web interface to set up the custom
domain (under Settings / Custom Domain). If you use the web interface, GitHub
will create the `CNAME` file for you and save it to the root of your "pages"
branch. So that the file does not get removed the next time you deploy, you need
to copy the file to your `docs_dir`. With the file properly included in your
`docs_dir`, MkDocs will include the file in your built site and push it to your
"pages" branch each time you run the `gh-deploy` command.
If you are having problems getting a custom domain to work, see GitHub's
documentation on [Troubleshooting custom domains].
[GitHub]: https://github.com/
[GitHub Pages]: https://pages.github.com/
@@ -87,6 +107,10 @@ files locally.
[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
[Custom Domain]: https://help.github.com/articles/adding-or-removing-a-custom-domain-for-your-github-pages-site
[docs_dir]: ./configuration.md#docs_dir
[CNAME file]: https://github.com/mkdocs/mkdocs/blob/master/docs/CNAME
[Troubleshooting custom domains]: https://help.github.com/articles/troubleshooting-custom-domains/
## Read the Docs