77 lines
2.8 KiB
Markdown
77 lines
2.8 KiB
Markdown
title: GitHub Pages
|
|
---
|
|
summary: Deploys to GitHub Pages.
|
|
---
|
|
body:
|
|
|
|
* `ghpages://username/repository`
|
|
* `ghpages+https://username/repository`
|
|
|
|
A popular way to host websites for Open Source projects is the GitHub pages.
|
|
It's a free service provided by [GitHub :ext](http://github.com/) which allows
|
|
to host completely static websites through GitHub.
|
|
|
|
The way this is implemented in Lektor currently is that Lektor will force-push
|
|
a website into a repository of choice. There are two ways to push it up:
|
|
`ghpages` (which uses SSH) or `ghpages+https` (which uses HTTPS). The latter
|
|
can also accept `username:password@` in the URL to hold the credentials in
|
|
addition to accepting username and password from the command line or
|
|
environment variables.
|
|
|
|
Example:
|
|
|
|
```ini
|
|
[servers.ghpages]
|
|
target = ghpages://your-user/your-repository
|
|
```
|
|
|
|
## Credentials
|
|
|
|
This deployment method has two implementations: `ghpages` (also known as
|
|
`ghpages+ssh`) which uses SSH and `ghpages+https` which uses HTTPS. They
|
|
use different methods for credentials. For the SSH transport the same
|
|
rules apply as for the [rsync deployment method :ref](../rsync/). The HTTPS
|
|
transport on the other hand accepts `--username` and `--password` which
|
|
override the values in the URL.
|
|
|
|
! If you have 2-factor authentication set up and you're using HTTPS, instead of your normal password, you will need to use a [personal access token :ext](https://help.github.com/articles/creating-a-personal-access-token-for-the-command-line/).
|
|
|
|
## Behavior
|
|
|
|
The way this deployment support works is that it commits a new commit into a
|
|
temporary location and pushes it into the `gh-pages` or `master` branch
|
|
depending on the name of the repository. If you push to `username.github.io`
|
|
then it commits to `master`, otherwise to `gh-pages`. This is consistent
|
|
with behavior for GitHub Pages.
|
|
|
|
## CNAME Support
|
|
|
|
If you want to use a custom domain with GitHub pages (also known as a
|
|
[CNAME :ext](https://en.wikipedia.org/wiki/CNAME)), provide the intended
|
|
CNAME in the target URL using the `?cname` parameter:
|
|
|
|
```ini
|
|
[servers.production]
|
|
target = ghpages://your-user/your-repository?cname=www.example.com
|
|
```
|
|
|
|
Note that this will overwrite whatever custom domain you may have set on
|
|
GitHub with every deployment.
|
|
|
|
For more information about how CNAMEs work with GitHub you can read about
|
|
the feature in the GitHub help center:
|
|
[Adding a CNAME file to your repository
|
|
:ext](https://help.github.com/articles/adding-a-cname-file-to-your-repository/).
|
|
|
|
## 404 Pages
|
|
|
|
Per convention the file named `404.html` is used as placeholder if a page
|
|
cannot be found. You can create such a page by creating a `404.html/contents.lr`
|
|
file.
|
|
|
|
## Automatic Deployments
|
|
|
|
If you want to use ghpages it's desirable to have this build automatically.
|
|
This is easy to accomplish with the help of Travis-CI. For more information
|
|
see [Deploying with Travis-CI :ref](../travisci/).
|