mirror of
https://github.com/lektor/lektor-website.git
synced 2025-04-02 00:11:50 +02:00
108 lines
4.4 KiB
Markdown
108 lines
4.4 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 [GitHub Pages :ext][github-pages].
|
|
It's a service provided by GitHub which allows one to host static websites for free.
|
|
|
|
[github-pages]: https://docs.github.com/en/pages/getting-started-with-github-pages/about-github-pages
|
|
|
|
The way this deployment support works is that it makes and pushes a new commit,
|
|
containing the current Lektor output, to a specific branch in a specified GitHub repository.
|
|
Lektor supports using either SSH or HTTPS to push to GitHub.
|
|
|
|
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 configuring the credentials.
|
|
|
|
For the SSH transport the same
|
|
rules apply as for the [rsync deployment method :ref](../rsync/).
|
|
|
|
For the HTTPS transport, there are three ways in which to provide credentials. In order of precedence (the first one found wins):
|
|
- By passing `--username` and `--password` parameters to the `lektor deploy` command.
|
|
- By setting the `$LEKTOR_DEPLOY_USERNAME` and `$LEKTOR_DEPLOY_PASSWORD` environment variables.
|
|
- In the _userinfo_ part of the target URL. E.g. `target = ghpages+https://user:pw@owner/repo-name`.
|
|
|
|
! 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/).
|
|
|
|
|
|
## Pushing To An Explicit Branch
|
|
|
|
You may explicitly specify which branch to push to by supplying a `?branch`
|
|
query parameter to target URL.
|
|
|
|
```ini
|
|
[servers.production]
|
|
target = ghpages://your-user/your-user.github.io?branch=main
|
|
```
|
|
|
|
If no branch is explicitly specified, then, when pushing to _owner_ or _organization_ sites
|
|
(where the repository name is of the form _owner_`.github.io`) the branch defaults to `master`.
|
|
For _project_ sites, the branch defaults to `gh-pages`.
|
|
|
|
! Around October 1, 2020, GitHub changed the default name of the default branch for newly created repositories from `master` to `main`. If you are deploying to a _user_ or _organization_ GitHub pages site that was created since then, you will likely have to explicitly specify which branch to push to.
|
|
|
|
## 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 a placeholder if a page
|
|
cannot be found. You can create such a page by creating a `404.html/contents.lr`
|
|
file.
|
|
|
|
|
|
## Pushing Orphan Commits
|
|
|
|
By default, when publishing to GH pages, the current head of the GH pages branch is fetched, a regular commit (with that parent) is made,
|
|
and then the new commit is pushed back to GitHub. This keeps the entire history of the site's built output in the git repository.
|
|
|
|
Keeping that history is of marginal utility, and doing things this way incurs the network overhead involved in fetching the current head.
|
|
|
|
Adding a `?preserve_history=no` query parameter to the target URL will cause orphan commits to be _force-pushed_ to the GH pages branch.
|
|
|
|
```ini
|
|
[servers.production]
|
|
target = ghpages://your-user/your-repo?preserve_history=no
|
|
```
|
|
|
|
! Setting `preserve_history=no`, while it avoids the network overhead involved in fetching the current head, _discards any history_ of the site's built output that may be kept in the target repository.
|
|
|
|
## 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/).
|
|
---
|
|
template_var:
|