Skip to content

Latest commit

 

History

History
223 lines (172 loc) · 6.13 KB

README-MAINTAINER.md

File metadata and controls

223 lines (172 loc) · 6.13 KB
Raw

Jekyll site CI

Maintainer info

This page documents how to maintain this site and update the web pages.

Prerequisites

To be able to run the Jekyll build process, the ruby interpreter and the gem tool are required. In latest macOS these tools are pre-installed, at least when Xcode or the Developer Command Line tools are present.

Install separate Homebrew

If you are like me and prefer really separated things, install a separate Homebrew instance, only for the jekyll builds.

mkdir -p "${HOME}/opt"
git clone https://github.com/ilg-ul/opt-install-scripts \
    "${HOME}/.local/install-scripts.git"

caffeinate bash
exec bash "${HOME}/.local/install-scripts.git/install-homebrew-jekyll.sh"

Add a new alias to your .profile:

alias ajkl='export PATH=/Users/ilg/.local/homebrew/jekyll/bin:${PATH}'

Then, in a new terminal:

$ ajkl
$ which ruby
/Users/ilg/.local/homebrew/jekyll/bin/ruby
$ ruby --version
ruby 2.6.3p62 (2019-04-16 revision 67580) [x86_64-darwin17]
$ gem --version
3.0.3
$ bundler --version
Bundler version 2.0.1

Alternately it is possible to link the desired bundle version locally, and run the npm scripts from VS Code:

mkdir -pv node_modules/.bin && \
rm -f node_modules/.bin/bundle && \
ln -sv  ${HOME}/.local/homebrew/jekyll/bin/bundle node_modules/.bin/bundle

Clone Git

To manage the web site, a local copy of this repository is required.

git clone https://github.com/xpack/web-jekyll.git web-jekyll.git

Install jekyll & gems

Install jekyll and all gems referred in Gemfile. Probably usually there is no need to run bundler as root, it can ask for sudo if needed, but in my setup it looks necessary.

$ cd web-jekyll.git
$ bundle install
$ bundle exec jekyll --version
jekyll 4.4.2

Development

The current development cycle is edit-save-build-view.

The build can be performed automatically by Jekyll when started in server mode.

cd web-jekyll.git
bundle exec jekyll serve --trace --safe --baseurl "/web-preview"

To view the result, point the browser to http://localhost:4002/web-preview/.

To test links:

bundle exec jekyll build
bundle exec htmlproofer --allow-hash-href --url-swap \^/web-preview/\:/ ./_site
bundle exec htmlproofer --allow-hash-href --url-swap \^/web-preview/\:/ \
  --url-ignore /github.com/xpack/xpack.github.io/blob/master/ ./_site

Publish

To publish, commit this Git and the new site will be automatically generated by GitHub Pages using Jekyll.

Updates

When new versions of Jekyll, or of gems, are available, activate the Jekyll environment (ajkl) run bundle update and be sure the Gemfile.lock file is committed.

Alternately use the npm script bundle-update.

$ cd web-preview.git
$ bundle update
Fetching gem metadata from https://rubygems.org/..........
Fetching gem metadata from https://rubygems.org/.
Resolving dependencies...
Fetching public_suffix 4.0.6 (was 3.1.1)
Installing public_suffix 4.0.6 (was 3.1.1)
Fetching addressable 2.7.0 (was 2.6.0)
Installing addressable 2.7.0 (was 2.6.0)
Using bundler 2.0.1
Using colorator 1.1.0
Fetching concurrent-ruby 1.1.7 (was 1.1.5)
Installing concurrent-ruby 1.1.7 (was 1.1.5)
Using eventmachine 1.2.7
Using http_parser.rb 0.6.0
Using em-websocket 0.5.1
Fetching ffi 1.13.1 (was 1.11.1)
Installing ffi 1.13.1 (was 1.11.1) with native extensions
Using ethon 0.12.0
Using forwardable-extended 2.6.0
Using mercenary 0.3.6
Using mini_portile2 2.4.0
Fetching nokogiri 1.10.10 (was 1.10.4)
Installing nokogiri 1.10.10 (was 1.10.4) with native extensions
Fetching nokogumbo 2.0.2
Installing nokogumbo 2.0.2 with native extensions
Fetching parallel 1.19.2 (was 1.17.0)
Installing parallel 1.19.2 (was 1.17.0)
Using rainbow 3.0.0
Fetching typhoeus 1.4.0 (was 1.3.1)
Installing typhoeus 1.4.0 (was 1.3.1)
Fetching yell 2.2.2 (was 2.2.0)
Installing yell 2.2.2 (was 2.2.0)
Fetching html-proofer 3.15.3 (was 3.11.1)
Installing html-proofer 3.15.3 (was 3.11.1)
Using i18n 0.9.5
Using rb-fsevent 0.10.4 (was 0.10.3)
Using rb-inotify 0.10.1 (was 0.10.0)
Using sass-listen 4.0.0
Using sass 3.7.4
Using jekyll-sass-converter 1.5.2
Using listen 3.2.1 (was 3.1.5)
Using jekyll-watch 2.2.1
Using rexml 3.2.4
Using kramdown 2.3.0 (was 1.17.0)
Using liquid 4.0.3 (was 4.0.0)
Using pathutil 0.16.2
Using rouge 3.23.0 (was 2.2.1)
Using safe_yaml 1.0.5
Using jekyll 3.9.0 (was 3.8.5)
Using jekyll-feed 0.15.0 (was 0.11.0)
Using posix-spawn 0.3.15
Using jekyll-last-modified-at 1.3.0
Using jekyll-redirect-from 0.16.0 (was 0.14.0)
Using jekyll-seo-tag 2.6.1 (was 2.5.0)
Using jekyll-sitemap 1.4.0 (was 1.2.0)
Using kramdown-parser-gfm 1.1.0
Bundle updated!

People using forked repositories must run bundle install to be sure the required versions are properly installed.

Add tags

bash scripts/createtag.sh XXX

Redirect

If pages are moved to a different URL, leave a redirect behind:

redirect_from:
  - /blog/2022/04/17/xpm-v0-13-0-released/

Links

Other:

Quick copy/paste

bundle exec jekyll serve --trace --safe --baseurl "/web-preview"

bundle exec jekyll serve --trace --safe

bundle exec jekyll build

bundle exec htmlproofer --allow-hash-href --url-swap \^/web-preview/\:/ ./_site_local

bundle exec htmlproofer --allow-hash-href --url-swap \^/web-preview/\:/ --url-ignore /github.com/xpack/xpack.github.io/blob/master/ ./_site_local

bundle exec htmlproofer --allow-hash-href ./_site_local

bundle exec htmlproofer --allow-hash-href --http_status_ignore=429 ./_site_local