search

chrisrhymes / bulma-clean-theme

A clean and modern Jekyll theme based on Bulma
http://www.csrhymes.com/bulma-clean-theme/
MIT License
383 stars 485 forks source link

Theme ignored after upgrading to v1 #151

Closed donkirkby closed 4 months ago

donkirkby commented 4 months ago

I've been using your theme for a few years, and I really like it. Thanks for publishing it.

Unfortunately, it seems to have broken for me after your recent changes upgrading to v1. When I push to my repository, the deployment to GitHub pages fails.

I tried to follow your instructions to upgrade, and I got it to deploy the site, but now it seems to have no theme at all!

Here's my config.yml:

remote_theme: chrisrhymes/bulma-clean-theme
title: Book Blender
google_analytics: UA-4644630-2
baseurl: /book-blender

defaults:
  - scope:
      path: ""
    values:
      hero_image: /book-blender/images/index_hero.jpg
      hero_darken: true
      twitter:
        card: summary_large_image
      image: images/index_hero.jpg

Here's my Gemfile:

source 'https://rubygems.org'
gem 'jekyll'

You can see the project at donkirkby/book-blender.

I thought maybe I shouldn't be using it as a remote theme but as a gem theme, but that didn't show up either.

It's unfortunate that this breaks projects. Is there a way for projects to continue using the old version until they want to upgrade? Is there a way to learn about upcoming changes to your theme?

Let me know if I can help with documentation or some coding. I contributed a few small patches back in 2020.

donkirkby commented 4 months ago

OK, I got it to work after a bunch of experimenting. I generally followed your upgrade guide and the Jekyll docs for GitHub Actions, although the workflow file needed some tweaks when my site is in the docs subfolder.

The trickiest parts for me to figure out were:

  1. Upgrade to Ruby 3.1. That was tricky, because it's not available on RVM stable. I had to run rvm get head as root.
  2. Install bulma-clean-theme as a gem in Gemfile. I ended up with jekyll and bulma-clean-theme.
  3. In _config.yml, change remote_theme: chrisrhymes/bulma-clean-theme to theme: bulma-clean-theme.
  4. In the same file, add layout: page to the default values section.
  5. I had overridden the footer to add a link to edit the page on GitHub. That didn't work anymore, and I couldn't get the jekyll-github-metadata gem to work. Instead, I replaced {% github_edit_link "Improve this page" %} with <a href="https://github.com/donkirkby/book-blender/blob/main/docs/{{page.path}}">Improve this page</a>.
  6. Update all local links to remove the .md extensions. I guess the newer version of Jekyll doesn't convert those to .html anymore.

So it all seems to be solvable, it was just a bit of a panic when it had suddenly broken.

If I hadn't gotten that to work, I realized that I could have extracted all the files from the theme gem and put them in the _includes folder. I haven't tried it, but I think it should work if a project wants to pin themselves to the old version.