From e17e00e5ae72c728fb43df3eea408d089dacfdeb Mon Sep 17 00:00:00 2001 From: Jeff Dairiki Date: Fri, 22 Jul 2022 10:44:14 -0700 Subject: [PATCH] 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: