From 6b2af81ac5cdc28a060e8ba80213dc8a54b8f97c Mon Sep 17 00:00:00 2001 From: Jeff Dairiki Date: Mon, 28 Feb 2022 15:00:24 -0800 Subject: [PATCH 1/2] Update /docs/deployment/ghpages for lektor/lektor#995 --- content/docs/deployment/ghpages/contents.lr | 55 ++++++++++++++------- 1 file changed, 37 insertions(+), 18 deletions(-) diff --git a/content/docs/deployment/ghpages/contents.lr b/content/docs/deployment/ghpages/contents.lr index 672362ae..52a281da 100644 --- a/content/docs/deployment/ghpages/contents.lr +++ b/content/docs/deployment/ghpages/contents.lr @@ -7,16 +7,15 @@ 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. +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. -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. +[github-pages]: https://docs.github.com/en/pages/getting-started-with-github-pages/about-github-pages + +The way this is implemented in Lektor currently is that Lektor will force-push +the lektor output to a specific branch in a repository of choice. +There are two ways to push it up: +`ghpages` (which uses SSH) or `ghpages+https` (which uses HTTPS). Example: @@ -25,24 +24,44 @@ Example: 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. +use different methods for 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 (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/). ## 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. +The way this deployment support works is that it makes a pushes a new commit, +containing the current Lektor output, to a specific branch in a specified Github repository. + +## 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 From e17e00e5ae72c728fb43df3eea408d089dacfdeb Mon Sep 17 00:00:00 2001 From: Jeff Dairiki Date: Fri, 22 Jul 2022 10:44:14 -0700 Subject: [PATCH 2/2] Document new `?preserve_history=no` parameter --- content/docs/deployment/ghpages/contents.lr | 40 +++++++++++++-------- 1 file changed, 26 insertions(+), 14 deletions(-) diff --git a/content/docs/deployment/ghpages/contents.lr b/content/docs/deployment/ghpages/contents.lr index 52a281da..48990b16 100644 --- a/content/docs/deployment/ghpages/contents.lr +++ b/content/docs/deployment/ghpages/contents.lr @@ -12,10 +12,9 @@ It's a service provided by GitHub which allows one to host static websites for f [github-pages]: https://docs.github.com/en/pages/getting-started-with-github-pages/about-github-pages -The way this is implemented in Lektor currently is that Lektor will force-push -the lektor output to a specific branch in a repository of choice. -There are two ways to push it up: -`ghpages` (which uses SSH) or `ghpages+https` (which uses HTTPS). +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: @@ -24,28 +23,22 @@ Example: 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. +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 (first one found wins): +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/). -## Behavior - -The way this deployment support works is that it makes a pushes a new commit, -containing the current Lektor output, to a specific branch in a specified Github repository. ## Pushing To An Explicit Branch @@ -77,19 +70,38 @@ 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 +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 +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: