From beb5a3af4169c3244091d56c922d4d26394a2d81 Mon Sep 17 00:00:00 2001 From: Daniel Egger Date: Sat, 24 Aug 2019 19:06:07 +0200 Subject: [PATCH] Universalize the GitHub pages publishing scheme (#780) Added instructions on how to publish to .github.io or .github.io by changing the publishing branch in the repo to `master`. This should work for any type of GitHub publishing, including custom domains. Fixes #765 --- docs/content/documentation/deployment/github-pages.md | 11 ++++++----- 1 file changed, 6 insertions(+), 5 deletions(-) diff --git a/docs/content/documentation/deployment/github-pages.md b/docs/content/documentation/deployment/github-pages.md index 049307c5..b9a60a27 100644 --- a/docs/content/documentation/deployment/github-pages.md +++ b/docs/content/documentation/deployment/github-pages.md @@ -4,8 +4,7 @@ weight = 30 +++ By default, GitHub Pages uses Jekyll (A ruby based static site generator), -but you can use whatever you want provided you have an `index.html` file in the root of a branch called `gh-pages`. -That branch name can also be manually changed in the settings of a repository. +but you can also publish any generated files provided you have an `index.html` file in the root of a branch called `gh-pages` or `master`, in addition you can also publish from a `docs` directory in your repository. That branch name can also be manually changed in the settings of a repository. **However** this only applies to publishing in a custom domain, i.e. if you want to publish to a GitHub provided web service under the `github.io` domain, you can **only** use the `master` branch of your repository as explained [here](https://help.github.com/en/articles/configuring-a-publishing-source-for-github-pages), so we will focus on the method which will work regardless of the domain. We can use any CI server to build and deploy our site. For example: @@ -45,6 +44,8 @@ Make sure "Display value in build log" is off, and then click add. Now Travis ha We're almost done. We just need some scripts in a .travis.yml file to tell Travis what to do. +**NOTE**: The script below assumes that we're taking the code from the `code` branch and will generate the HTML to be published in the `master` branch of the same repository. You're free to use any other branch for the Markdown files but if you want to use `.github.io` or `.github.io`, the destination branch **MUST** be `master`. + ```yaml language: minimal @@ -59,12 +60,12 @@ script: # If you are using a different folder than `public` for the output directory, you will # need to change the `zola` command and the `ghp-import` path after_success: | - [ $TRAVIS_BRANCH = master ] && + [ $TRAVIS_BRANCH = code ] && [ $TRAVIS_PULL_REQUEST = false ] && zola build && sudo pip install ghp-import && - ghp-import -n public && - git push -fq https://${GH_TOKEN}@github.com/${TRAVIS_REPO_SLUG}.git gh-pages + ghp-import -n public -b master && + git push -fq https://${GH_TOKEN}@github.com/${TRAVIS_REPO_SLUG}.git master ``` If your site is using a custom domain, you will need to mention it in the `ghp-import` command: `ghp-import -c vaporsoft.net -n public`