You can not select more than 25 topics Topics must start with a letter or number, can include dashes ('-') and can be up to 35 characters long.

github-pages.md 3.9KB

1234567891011121314151617181920212223242526272829303132333435363738394041424344454647484950515253545556575859606162636465666768697071727374
  1. +++
  2. title = "GitHub Pages"
  3. weight = 30
  4. +++
  5. By default, GitHub Pages uses Jekyll (A ruby based static site generator),
  6. 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.
  7. We can use any CI server to build and deploy our site. For example:
  8. * [Github Actions](https://github.com/shalzz/zola-deploy-action)
  9. * [Travis CI](#travis-ci)
  10. ## Travis CI
  11. We are going to use [TravisCI](https://travis-ci.org) to automatically publish the site. If you are not using Travis already,
  12. you will need to login with the GitHub OAuth and activate Travis for the repository.
  13. Don't forget to also check if your repository allows GitHub Pages in its settings.
  14. ## Ensure Travis can access your theme
  15. Depending on how you added your theme Travis may not exactly know how to access
  16. it. The best way to ensure it will have full access to the theme is to use git
  17. submodules. When doing this ensure you are using the `https` version of the URL.
  18. ```shell
  19. $ git submodule add {THEME_URL} themes/{THEME_NAME}
  20. ```
  21. ## Allowing Travis to push to GitHub
  22. Before pushing anything, Travis needs a Github private access key in order to make changes to your repository.
  23. If you're already logged in to your account, just click [here](https://github.com/settings/tokens) to go to your tokens page.
  24. Otherwise, navigate to `Settings > Developer Settings > Personal Access Tokens`.
  25. Generate a new token, and give it any description you'd like.
  26. Under the "Select Scopes" section, give it repo permissions. Click "Generate token" to finish up.
  27. Your token will now be visible!
  28. Copy it into your clipboard and head back to Travis.
  29. Once on Travis, click on your project, and navigate to "Settings". Scroll down to "Environment Variables" and input a name of `GH_TOKEN` with a value of your access token.
  30. Make sure "Display value in build log" is off, and then click add. Now Travis has access to your repository.
  31. ## Setting up Travis
  32. We're almost done. We just need some scripts in a .travis.yml file to tell Travis what to do.
  33. **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 `<username>.github.io` or `<org>.github.io`, the destination branch **MUST** be `master`.
  34. ```yaml
  35. language: minimal
  36. before_script:
  37. # Download and unzip the zola executable
  38. # Replace the version numbers in the URL by the version you want to use
  39. - curl -s -L https://github.com/getzola/zola/releases/download/v0.8.0/zola-v0.8.0-x86_64-unknown-linux-gnu.tar.gz | sudo tar xvzf - -C /usr/local/bin
  40. script:
  41. - zola build
  42. # If you are using a different folder than `public` for the output directory, you will
  43. # need to change the `zola` command and the `ghp-import` path
  44. after_success: |
  45. [ $TRAVIS_BRANCH = code ] &&
  46. [ $TRAVIS_PULL_REQUEST = false ] &&
  47. zola build &&
  48. sudo pip install ghp-import &&
  49. ghp-import -n public -b master &&
  50. git push -fq https://${GH_TOKEN}@github.com/${TRAVIS_REPO_SLUG}.git master
  51. ```
  52. 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`
  53. for example.
  54. Credits: this page is based on the article https://vaporsoft.net/publishing-gutenberg-to-github/