Default deploy workflow breaks with custom plugins like jekyll-toc or jekyll-terser

[mhmoslemi2338]

Have you checked that your issue isn't already filed?

• I read through FAQ and searched through the past issues, none of which addressed my issue.
• Yes, I have checked that this issue isn't already filed.

Bug description

The default GitHub Actions workflow (actions/jekyll-build-pages@v1) included in this template fails to deploy the site when using custom Jekyll plugins such as jekyll-toc, jekyll-terser, etc. These plugins work perfectly in local builds, but GitHub Pages throws Liquid errors or dependency issues because the GitHub-managed environment uses the restricted github-pages gem and older Jekyll version.

How to reproduce the bug

1- Fork or clone the repo and follow setup instructions

2- Add a plugin like jekyll-toc or jekyll-terser to the Gemfile

3- Reference {% toc %} in a layout or markdown file

4- Push to GitHub with the default actions/jekyll-build-pages@v1 workflow

5- Observe build failure in Actions tab

Error messages and logs

Liquid Exception: Liquid syntax error (line 61): Unknown tag 'toc' in /_layouts/post.liquid

The github-pages gem can't satisfy your Gemfile's dependencies.
https://github.com/RobertoJBeltran/jekyll-terser.git is not yet checked out. Run bundle install first.

What operating system are you using?

Mac

Where are you seeing the problem on?

Deployed site

More info

✅ Temporary Fix / Workaround

I replaced the final step in .github/workflows/deploy.yml with the following:

  - name: Deploy 🚀
    if: github.event_name != 'pull_request'
    uses: JamesIves/github-pages-deploy-action@v4
    with:
      branch: gh-pages
      folder: _site
      clean: true

Then, in Settings → Pages, I changed the Build and deployment source to:

Deploy from a branch → gh-pages branch → /(root)

After these changes:

• The GitHub Actions workflow now builds the site using bundle exec jekyll build with all custom plugins (e.g., jekyll-toc, jekyll-terser, etc.)
• The site is correctly deployed to the gh-pages branch
• Although some minor warnings still appear in the logs, the site is now up and running smoothly

This workaround bypasses the limitations of actions/jekyll-build-pages@v1, which cannot handle custom plugins due to its reliance on the github-pages gem.

[sanket-dse]

Hey I don't see any gh-pages branch and the pages-build-deployment workflow run still fails after making the suggested changes. I am on Windows 11. Although all these changes were done in the browser itself. Any suggestions are welcome

[george-gca]

You should NOT use actions/jekyll-build-pages@v1 workflow. We already have a built-in workflow that handles building and deploying the page correctly.