Snowlake Jekyll documentation

Deploy to GitHub Pages

Publish Snowlake on GitHub Pages with the included GitHub Actions workflow, at username.github.io/repo-name/, username.github.io or your own domain.

Overview

Snowlake comes with a ready-made GitHub Actions workflow, .github/workflows/pages.yml, that builds the site and publishes it to GitHub Pages every time you push to main. Setup is one setting in your repository.

GitHub’s older “Deploy from a branch” option can’t build Snowlake: it runs an old Jekyll with a fixed list of plugins and skips Snowlake’s pagination and archive plugins. Use GitHub Actions as the source, as described below.

Before you start

  • Repository visibility. GitHub Pages is free for public repositories. Publishing from a private repository needs a paid GitHub plan (Pro, Team or Enterprise).
  • Branch name. The workflow publishes from main. If your branch is called something else, change branches: [main] near the top of .github/workflows/pages.yml.
  • Keep the .github folder. It is hidden on some computers, so make sure it is copied when you move the theme files into your repository.

Publish your site

  1. Push the theme to a GitHub repository.
  2. In the repository, open Settings > Pages.
  3. Under Build and deployment, set Source to GitHub Actions.
  4. Open the Actions tab. If the first run started before you changed the setting and failed, open it and choose Re-run all jobs. Otherwise push any change, or open Deploy to GitHub Pages and choose Run workflow.
  5. When the run finishes (about two minutes), your site is live. The address is shown in the run summary and under Settings > Pages.

Every later push to main publishes the site again.

Site address and subfolder

You don’t need to edit url or baseurl in _config.yml for GitHub Pages. The workflow reads the address from your Pages settings and sets both for the build.

Repository Site address
username.github.io https://username.github.io/
Any other name, such as my-site https://username.github.io/my-site/
Any repository with a custom domain https://your-domain.com/

When the site lives in a subfolder (/my-site/), Snowlake adds the subfolder to every link and image path when it builds. Keep writing paths from the site root, such as /assets/images/my-photo.webp or /contact/, in pages, posts and data files; they keep working if you later move to your own domain.

To preview a subfolder site on your computer, pass the subfolder to Jekyll and open http://localhost:4000/my-site/:

bundle exec jekyll serve --baseurl /my-site

Use your own domain

  1. In Settings > Pages, enter your domain under Custom domain and save.
  2. Add the DNS records GitHub shows at your domain provider.
  3. Turn on Enforce HTTPS once it becomes available.
  4. Run the workflow again (push a change or choose Run workflow) so the site is rebuilt with the new address.

Troubleshooting

The run fails at “Read the Pages settings”. Pages isn’t set to use GitHub Actions yet. Set Source to GitHub Actions (step 3 above) and re-run the workflow.

The run fails at “Publish to GitHub Pages” with a branch protection message. The github-pages environment only allows certain branches. In Settings > Environments > github-pages, allow the branch you publish from.

The site shows plain text without styles, or only the README. Pages is still set to Deploy from a branch. Switch the source to GitHub Actions.

Nothing happens when you push. Check that .github/workflows/pages.yml is in your repository and that you pushed to the branch named in the workflow.

Google Analytics shows no visits. Set google_analytics.enable to true in _data/general_settings.yml. The workflow already builds in production mode.