GitHub Pages on Windows
10 Sep 2023 Jekyll on Windows (8.1)
GitHub Pages - too good to be true (literally)
Jekyll on Windows 24 October 2018 documentation
was for me doomed,
provoking many false moves that needed undoing.
10 Sep 2023 instructions seem OK,
so far as it goes (not nearly far enough)…
Debugging Jekyll page generation wants a GitHub Pages repository local copy,
but jekyll new
creates a GitHub Pages for blogging;
Jekyll for pages is configured rather differently.
Two files control Jekyll page generation: Gemfile
and _config.yml
.
Gemfile
identifies Ruby Gems for Jekyll to format according to ``_config.yml`.- Jekyll uses
bundle
to manage resources; instead of directly invokingjekyll
,
one invokes e.g.
bundle exec jekyll serve --incremental --trace --baseurl=""
Jekyll is a Ruby gem
Jekyll depends on many other gems via Bundler, yet another gem.
The first 2 steps in GitHub Pages generation involves installing a Ruby+Devkit.
For Windows, do this using RubyInstaller, because:
- RubyInstaller is the least hassle way to get a newer version.
- Jekyll infrastructures eventually require updating,
e.g. for
nokogiri
vulnerabilities - Older Ruby versions sooner than later fail to support updates of e.g.
nokogiri
. - GitHub will refuse to deploy Pages updates until security vulnerabilites are resolved.
- Ruby and its gems are liable to breaking changes, requiring a new Ruby version.
Here is a worthwhile Jekyll Gemfile
for GitHub Pages, not a blog:
source 'http://rubygems.org'
gem 'wdm', '>= 0.1.0' if Gem.win_platform?
gem 'github-pages', group: :jekyll_plugins
gem "webrick", "~> 1.8"
gem "faraday-retry", "~> 2.2"
group :jekyll_plugins do
gem 'jekyll-commonmark-ghpages'
end
group: :jekyll_plugins
is key to matching GitHub Page’s appearance.gem 'jekyll-commonmark-ghpages'
approximates GitHub Page’s page generator.
Here is a working example Jekyll _config.yml
for GitHub Pages:
theme: jekyll-theme-tactile
repository: blekenbleu/blekenbleu.github.io
github: [metadata]
markdown: CommonMarkGhPages
url: 'https://blekenbleu.github.io/'
Install GitHub Desktop
- includes
git.exe
useful with Rubymsys64
Bash console. - free for non-commercial use
- [Clone a repository refuses to clone into an existing directory]
Install Ruby with Dev toolchain
Installing without admin permissions works for me…
GitHub documentation
was unclear, but Jekyll depends on nokogiri, which has C extensions,
and "MSYS2 is required to install gems with C extensions"
Invoke commands from some Bash shell
- Launch Ruby’s
msys64\ucrt64.exe
Bash console. ``` Copying skeleton files. These files are for the users to personalise their msys2 experience.
They will never be overwritten nor automatically updated.
’./.bashrc’ -> ‘/home/bleke/.bashrc’ ‘./.bash_logout’ -> ‘/home/bleke/.bash_logout’ ‘./.bash_profile’ -> ‘/home/bleke/.bash_profile’ ‘./.inputrc’ -> ‘/home/bleke/.inputrc’ ‘./.profile’ -> ‘/home/bleke/.profile’
#### Generate a [personal access token](https://help.github.com/articles/creating-a-personal-access-token-for-the-command-line/)
This is wanted for local **Jekyll** as well as **GitHub Desktop**
##### set Jekyll's environmental variable:
Added to `~/.bash_profile` :
Ruby’s msys2 Bash $PATH by default includes neither git nor vi
if [ -z “$RUBY” ] ; then export RUBY=”/g/Ruby25-x64” fi if [ -d “${RUBY}/bin” ] ; then PATH=”${PATH}:${RUBY}/bin” fi
export JEKYLL_GITHUB_TOKEN=0123456789yourTokenHereabcdef98765432100 if [ -d /g/GitHub/blekenbleu.github.io ] ; then alias g=”cd /g/GitHub/blekenbleu.github.io” fi alias serve=”~/bin/serve”
Ctrl+C leaves Jekyll server running..!
alias unserve=”taskkill //IM ruby.exe //F”
`$ cat $HOME/bin/serve`
echo bundle exec jekyll serve –incremental –trace –baseurl=”” bundle exec jekyll serve –incremental –trace –baseurl=””
`$ gem install bundler`
- `gem` required firewall permissions
###
###
### Modify folder for **GitHub Pages**
`$ cd /e/blekenbleu.github.io`
`$ cat _config.yml`
#theme: jekyll-theme-minimal theme: jekyll-theme-tactile
theme: jekyll-theme-primer
repository: blekenbleu/blekenbleu.github.io #github: [metadata] #markdown: CommonMarkGhPages baseurl: “” # the subpath of your site, e.g. /blog url: “https://blekenbleu.github.io/” # the base hostname & protocol for your site
`$ cat Gemfile`
source ‘http://rubygems.org’
required for Jekyll to detect folder changes for –incremental
gem ‘wdm’, ‘>= 0.1.0’ if Gem.win_platform?
required for Jekyll to emulate GitHub Pages theme
gem ‘github-pages’ # Windows Jekyll: no theme #gem ‘github-pages’, group: :jekyll_plugins # GitHub Pages Action times out
required since Ruby 3.0 for bundle exec jekyll serve
gem “webrick”, “~> 1.8”
#### Install gems to support **GitHub Pages**
`$ bundle install`
#### serve simple test Jekyll
`$ cd blekenbleu.github.io/`
`$ serve`
Configuration file: D:/GitHub/blekenbleu.github.io/_config.yml Source: D:/GitHub/blekenbleu.github.io Destination: D:/GitHub/blekenbleu.github.io/_site Generating… Jekyll Feed: Generating feed for posts done in 0.752 seconds. Auto-regeneration: enabled for ‘D:/GitHub/blekenbleu.github.io’ Server address: http://127.0.0.1:4000/ Server running… press ctrl-c to stop. [2018-10-22 16:02:03] ERROR ‘/favicon.ico’ not found.
#### Browse to [http://localhost:4000](http://localhost:4000) to review results
###
###
Based on [this advice](https://github.com/mmistakes/minimal-mistakes/issues/1558)
... ignore this "*You must*" message:
Thank you for installing html-pipeline! You must bundle Filter gem dependencies. See html-pipeline README.md for more details. https://github.com/jch/html-pipeline#dependencies ```
Commit your working GitHub Page[s] to master and Push to GitHub
Best practices
Once pages are working, these steps minimize update hassles.
- Before changing markdown in GitHub Pages repository, update infrastructure:
gem update --system
- In repository, grab latest Jekyll gems:
bundle update
- Check infrastructure before making changes; generatng fresh HTML:
bundle exec jekyll clear
bundle exec jekyll serve --incremental --trace --baseurl=""
- Now, make changes. If other than trivial, better to repeat above 2 steps.
- if changing
Gemfile
or_config.yml
, should then
(beforebundle exec jekyll
):
bundle install
- if changing