Broken remote_theme with github_pages

[capape]

I use minima remote_theme to be able to use dark theme for github_pages:

# This is the default theme for new Jekyll sites. You may change this to anything you like.
gem "minima", "~> 2.5"
# If you want to use GitHub Pages, remove the "gem "jekyll"" above and
# uncomment the line below. To upgrade, run `bundle update github-pages`.
gem "github-pages", "~> 228", group: :jekyll_plugins

My config is

remote_theme: jekyll/minima

plugins:  
  - jekyll-feed

minima:
  skin: dark

Last changes have broken this theme. I does not handle headers and social links well. Right now I forked the repo and reverted the changes in my forked copy to be able to use the theme

remote_theme: capape/minima

plugins:  
  - jekyll-feed

minima:
  skin: dark

Expected:

Actual:

Regards,
Antonio Capapé.

[ashmaroli]

Hello @capape,
I would like to inform you that the recent changes you have reverted in your fork of the Minima Jekyll Theme were intentional and part of introducing non-backwards-compatible changes in Minima v3.
The "break" you had encountered is primarily due to change in configuration keys which have been documented via updates to the README.
I hope you will try the recent changes by making necessary changes to your config and provide feedback regarding this issue ticket.

With all that said, the master branch is still unstable and may introduce additional changes that would be incompatible with existing code.

P.S. In case you didn't know, you can lock-onto a particular commit via the remote-theme plugin as well:

remote_theme: "jekyll/minima@93b1921"

[capape]

Thank you @ashmaroli

My first attempt was to upgrade to Minima v3, but I was not able to do it following the README, as it reported some problems when launching the bundle. That's why I forked and reverted changes (I didn't know that I can hook to a particular commit).

In the next days I will try again and report my findings.

[Polovinkin]

have the same issue, and couldn't get what went wrong, now I see
it's kinda scary that the random update from your side can be actually non-compatible with existing code and just break the websites people make using Minima

that's the PR with breaking change btw, for reference - #856

[Polovinkin]

https://github.com/jekyll/minima?tab=readme-ov-file#customize-navigation-links is the exact place where those changes are mentioned, tho, for those who will also wonder where those "keys which have been documented via updates" actually are

[ashmaroli]

it's kinda scary that the random update from your side can be actually non-compatible with existing code and just break...

Technically, it wasn't a random update. It was an intentional change made as per principles of Semantic Versioning. The master branch is at 3.0.0.dev to communicate that the branch is currently under development of a semver-major (v2.5.x -> v3.0.x) release.

Moreover, every significant change has been documented to ease migration. But now I realise that the README needs one more disclaimer in bold explicitly stating that the development nature of master branch and not pinning to a particular git-ref via remote_theme is risky.

[Polovinkin]

yeah, I think additional disclaimer would be handy, as many would probably expect for master branch to be stable :)) At least I thought so, so thanks for the info!

[ashmaroli]

additional disclaimer would be handy...

Already done via #861

[ollpu]

Good that there's a warning in the README now. The example _config.yml still suggests pointing to master, however:

minima/_config.yml

Lines 18 to 21 in 43f3ed0

	# As of November 2023, GitHub Pages still uses Minima 2.5.1 (https://pages.github.com/versions/).
	# If you want to use the latest Minima version on GitHub Pages, use the following setting and
	# add a line comment on "theme: minima" above.
	#remote_theme: jekyll/minima

That being there likely means that a lot of users are using the theme without a pinned version. Not sure what can be done about that. Is it possible to give a direct warning to the user if the theme detects the config remote_theme: jekyll/minima without a version specifier?

Long term I would make the version specifier in jekyll-remote-theme mandatory, but that's a different discussion.

[codeRSH]

I have gone through the README now and understand what happened, but till yesterday I was confused what wrong did I do that broke my blog!

While keeping the Gemfile to a particular commit version works, that essentially 'stops' me from using the latest Minima V3. But on the other hand, using the latest HEAD commit is essentially using the DEV version of the product in Production! So, it's a trade off either ways.

I have encountered a few breaking changes in last few months. So, I don't want to spend my time debugging and correcting and adjusting my blog's theme rather than actually writing the content on the blog (the main reason behind starting the blog!). So, I guess I will stay with the Feb 27th version for now.

But I am willing to invest time and efforts to adjust my local theme to all the breaking changes, once the V3 goes 'live'.
I know this has been asked multiple times before, but is there any 'soft deadline' of releasing the final Minima V3? This year? By 2027?

[harisont]

Hi!

I decided to try and adapt my config to the latest changes, but that only worked in part.
My header now only displays the nav pages listed in my config, but does so twice, and I'm not sure why (I don't have a custom header or anything like that).

[ashmaroli]

Hello @harisont,
The reason behind the issue with your site is that your repository contains Sass partials from an older commit of Minima v3 under _sass/minima/**.scss (most probably made to customize styles), which prevents Jekyll from loading the newer versions of those sass partials, which ultimately results in having markup and css rules out of sync with each other.
The solution here is to either lock-in to the commit corresponding to the your repository's sass partials or manually copy over sass partials from latest commit at jekyll/minima and re-apply your style customizations on those (newly-copied-over sass partials).

[harisont]

@ashmaroli thank you! Locked for now, but in the future we'll see

[JohannCSP]

Hi,

I faced the same issues with my social icons disappearing after the updates to migrate to Font Awesome in the dev branch. However, after some digging into the changes I managed to adapt my config to make it work.

Below the steps I used in case it saves time to anyone doing the same.

1. Update your _config.yml with the new format for social_links and disable the old section.

minima:
  social_links:
    - title: Jekyll repository at GitHub
      icon: github
      url: "https://github.com/jekyll/jekyll"

2. Update your _includes/social.html with the latest from minima (I'm currently using 0b7ca6b). You can also delete _includes/social-item.html since it is not used anymore after the changes for Font Awesome.

3. Add the new import for the Fonts Awesome stylesheet. It was included in _includes/footer.html as of 0b7ca6b; however I had to add it in my _includes/custom-head.html since I'm not using a footer in my blog.

<link id="fa-stylesheet" rel="stylesheet" href="https://cdn.jsdelivr.net/npm/@fortawesome/fontawesome-free@latest/css/all.min.css">

4. You can customize the color and size of the icons from Font Awesome in the updated _includes/social.html. For instance, I removed the static grey and made it fa-2x to look almost identical to the previous one.

  <li>
    <a rel="me" href="{{ entry.url }}" target="_blank" title="{{ entry.title }}">
      <span class="fa-brands fa-{{ entry.icon }} fa-2x"></span>
    </a>
  </li>

5. Hope it helps!