From 860c5d63946c52100379c7f81739a33b5b2323fd Mon Sep 17 00:00:00 2001 From: nisbet-hubbard <87453615+nisbet-hubbard@users.noreply.github.com> Date: Sun, 22 Sep 2024 20:25:40 +0800 Subject: [PATCH] Improve docs around using GitHub Actions to build and deploy Jekyll sites (#9682) Merge pull request 9682 --- .../continuous-integration/github-actions.md | 37 ++++++++++++++----- docs/_docs/plugins/installation.md | 6 ++- 2 files changed, 31 insertions(+), 12 deletions(-) diff --git a/docs/_docs/continuous-integration/github-actions.md b/docs/_docs/continuous-integration/github-actions.md index caba322f..511f9a9c 100644 --- a/docs/_docs/continuous-integration/github-actions.md +++ b/docs/_docs/continuous-integration/github-actions.md @@ -2,21 +2,35 @@ title: GitHub Actions --- -When building a Jekyll site with GitHub Pages, the standard flow is restricted for security reasons -and to make it simpler to get a site setup. For more control over the build and still host the site -with GitHub Pages you can use GitHub Actions. +When building a Jekyll site with GitHub Pages, Jekyll runs in an environment restricted for security +reasons, yet containing numerous [whitelisted plugins and themes][ghp-whitelist] to make it simpler +to get a site set up. + +The only workaround to have control over the build environment and gemset yet use GitHub Pages to +host the site was previously by building elsewhere and pushing the built directory contents to the +`gh-pages` branch on your repository. + +However, GitHub now provides you with the option to use their in-house CI/CD product named +*GitHub Actions* to *build and deploy (host)* your Jekyll site with complete control over the build +environment and gemset. ## Advantages of using Actions ### Control over gemset -- **Jekyll version** --- Instead of using the classic GitHub Pages provided version at `3.9.3`, you +- **Jekyll version** --- Instead of using the classic GitHub Pages-provided version at `3.9.3`, you can use any version of Jekyll you want. For example `{{site.version}}`, or point directly to the - repository. -- **Plugins** --- You can use any Jekyll plugins irrespective of them being on the - [supported versions][ghp-whitelist] list, even `*.rb` files placed in the `_plugins` directory - of your site. -- **Themes** --- While using a custom theme is possible without Actions, it is now simpler. + repository via the Gemfile. +- **Plugins** --- You can use any Jekyll plugins irrespective of them being whitelisted by GitHub, + including any `*.rb` files placed in the `_plugins` directory of your site. +- **Themes** --- While using a custom theme is possible without Actions, it is now possible to use + themes depending on features introduced in newer versions of Jekyll. + +{: .note .info} +If you are migrating from the classic flow but want to keep using a GitHub-hosted theme, you may use +the [jekyll-remote-theme][remote-theme] plugin, add any required dependencies of your theme +(previously bundled by default) into your `_config.yml` and `Gemfile` and set the +`remote_theme: /` theme repository slug correctly in your `_config.yml`. ### Workflow Management @@ -24,6 +38,8 @@ with GitHub Pages you can use GitHub Actions. steps, use environment variables. - **Logging** --- The build log is visible and can be tweaked to be verbose, so it is much easier to debug errors using Actions. +- **Caching** --- The `ruby/setup-ruby` action makes it possible to cache installed gems + automatically instead of having to download the bundle on each build. ## Workspace setup @@ -31,7 +47,7 @@ The first and foremost requirement is a Jekyll project hosted at GitHub. Choose project or follow the [quickstart]({{ '/docs/' | relative_url }}) and push the repository to GitHub if it is not hosted there already. -The Jekyll site we'll be using for the rest of this page initially consists of just a `_config.yml`, +The Jekyll site we'll be using for the rest of this page, initially consists of just a `_config.yml`, an `index.md` page and a `Gemfile`. The contents are respectively: ```yaml @@ -117,5 +133,6 @@ The workflow will build and deploy your site again. - [starter-workflows] is the official repository providing the workflow template used in this guide. [ghp-whitelist]: https://pages.github.com/versions/ +[remote-theme]: https://github.com/benbalter/jekyll-remote-theme [timeago-plugin]: https://rubygems.org/gems/jekyll-timeago [starter-workflows]: https://github.com/actions/starter-workflows/blob/main/pages/jekyll.yml diff --git a/docs/_docs/plugins/installation.md b/docs/_docs/plugins/installation.md index dcfc4e43..f3f16c94 100644 --- a/docs/_docs/plugins/installation.md +++ b/docs/_docs/plugins/installation.md @@ -109,8 +109,10 @@ end --safe option to disable plugins (with the exception of some whitelisted plugins) for security reasons. Unfortunately, this means your plugins won't work if you’re deploying via GitHub Pages.

- You can still use GitHub Pages to publish your site, but you’ll need to build the site locally and push the generated files to your - GitHub repository instead of the Jekyll source files. + You can still use GitHub Pages to publish your site, but you'll need to either build the site locally and push the generated files to + your GitHub repository or use + GitHub Actions to host source + files on GitHub yet build and deploy with full control on GitHub Pages.