Jekyll on Windows 11 for GitHub Pages preview
Differences in Jekyll experiences on different Windows versionsare mostly about Ruby and Jekyll evolution and breaking changes.
Ruby installation has become more trouble-free, without hangs and need for retries.
Meanwhile, Jekyll functionality on Windows seems to have regressed:
jekyll new
markdown defaults to blog-specific format
Gemfile
configured for page appearances to match GitHub Pages theme      causes GitHub Pages deployment action to timeout:
$ diff Gemfile ../site 5c5 < gem 'github-pages' # Windows Jekyll: no theme --- > gem 'github-pages', group: :jekyll_plugins # GitHub Pages Action times out
This last issue differs between Jekyll on Windows and GitHub's Jekyll docker.
Fortunately, empty front matter suffices to enable markdown processing;
default title is overridden by a markdown ### heading immediately below front matter.
--- --- ### Custom Title
Over 60 markdown files in my GitHub Pages needing editting for these issues...
Work-arounds to match themed pages served on Windows vs GitHub Pages
- Spun out separate projects to reduce GitHub Pages commit times:
static
(folders without markdown), microscope, Arduino-Blue-Pill. - Deleted
Gemfile.lock
, pushed to GitHub, then added to.gitignore
.
GitHub Pages builds fine without it, the major source of dependabot issues. - Likewise, added
_site/
to.gitignore
. - On Windows,
unset JEKYLL_GITHUB_TOKEN
beforebundle exec jekyll serve
to avoid github-pages issues. - Serve local Jekyll from folder
site/
, which buildssite/_site/
from../blekenbleu.github.io/
, using custom_config.yml
:theme: jekyll-theme-tactile repository: blekenbleu/blekenbleu.github.io source: ../blekenbleu.github.io/
- In
site/_site/
, link:
microscope_site/
build folder,static/
andArduino-Blue-Pill/docs/
folders.
bundle exec jekyll serve --incremental
running insite/
detects changes in neithermicroscope
norArduino-Blue-Pill
;
each requiresbundle exec jekyll build
to update their_site/
folder.
- Regenerate and serve
blekenbleu.github.io/
(markdown) changes fromsite/
folder,
while changes to content linked insite/_site/
are served,
but transparent to its Jekyll regeneration.
Linking needs repeating wheneversite/_site/
gets regenerated;
links.bat
does that:cd _site mklink /d Arduino-Blue-Pill ..\..\..\Arduino\Blue-Pill\docs mklink /d microscope ..\..\microscope\_site mklink /d static ..\..\static
github-pages issues
To apply themes, Windows Jekyl requires inGemfile
:gem 'github-pages', group: :jekyll_plugins
Beyond that, with
JEKYLL_GITHUB_TOKEN
set, bundle exec jekyll serve
fails with:
Liquid Exception: The GitHub API credentials you provided aren't valid. in /_layouts/default.html $ bundle exec github-pages health-check (LoadError)4/lib/ruby/gems/3.2.0/gems/ffi-1.15.5/lib/ffi/library.rb:145:in `block in ffi_lib': Could not open library 'libcurl': The specified module could not be found. . Could not open library 'libcurl.dll': The specified module could not be found. . Could not open library 'libcurl.so.4': The specified module could not be found. . Could not open library 'libcurl.so.4.dll': The specified module could not be found....FWIW, there is no
/_layouts/default.html
.
Installed curl
, which did not help:
$ pacman -Sy mingw-w64-x86_64-curl $ find /f -name curl.h -print /f/Ruby32-x64/msys64/mingw64/include/curl/curl.h $ gem install curb --platform=ruby -- --with-curl-lib="F:/Ruby32-x64/msys64/mingw64/lib" --with-curl-include="F:/Ruby32-x64/msys64/mingw64/include" Temporarily enhancing PATH for MSYS/MINGW... Building native extensions with: '--with-curl-lib=F:/Ruby32-x64/msys64/mingw64/lib --with-curl-include=F:/Ruby32-x64/msys64/mingw64/include' This could take a while... Successfully installed curb-1.0.5 Parsing documentation for curb-1.0.5 Installing ri documentation for curb-1.0.5 Done installing documentation for curb after 0 seconds 1 gem installed...
bundle exec github-pages health-check
still fails the same way.Ruby updates
While Ruby gems can be updated, Ruby itself as installed by RubyInstaller cannot.Ruby is used here only for Jekyll, but its bundled MSYS2 gets used extensively,
with several packages added.  Before replacing Ruby,
run MSYS2 package manager to document its current package list:
pacman -Q > /d/oldMSYS2.txt
.. then compare with new MSYS2 for determining packages to add.
Of course, any MSYS2
home/user
folder customizations should also be ported.