Skip to content

Latest commit

 

History

History
272 lines (222 loc) · 8.55 KB

README.md

File metadata and controls

272 lines (222 loc) · 8.55 KB
Raw

Build Status

The xPack web site source

Overview

This GitHub project, available from xpack/xpack.github.io-source, contains the source files used to generate the xPack web site.

Destination URL

The xPack web site is an organisation GitHub Pages site, stored in the xpack/xpack.github.io Git and publicly available from http://xpack.github.io.

Jekyll

The web site is generated off-line by Jekyll. It cannot be generated by GitHub Pages because it uses Jekyll plug-ins, considered unsafe and disabled by the GitHub Pages instance of Jekyll.

Prerequisites

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

Install separate homebrew

If you are like me and like 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}/opt/install-scripts.git"
$ caffeinate bash 
$ exec bash "${HOME}/opt/install-scripts.git/install-homebrew-jekyll.sh"

Add a new alias to your .profile:

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

Then, in a new terminal:

$ ajkl
$ which ruby
/Users/ilg/opt/homebrew/jekyll/bin/ruby
$ ruby --version
ruby 2.4.2p198 (2017-09-14 revision 59899) [x86_64-darwin17]
$ gem --version
2.6.13
$ bundler --version
Bundler version 1.15.4

Clone Git

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

$ git clone https://github.com/xpack/xpack.github.io-source.git xpack.github.io-source.git
$ git clone https://github.com/xpack/xpack.github.io.git xpack.github.io.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 xpack.github.io-source.git
$ bundle install
The latest bundler is 1.16.0.pre.2, but you are currently running 1.15.4.
To update, run `gem install bundler --pre`
Fetching gem metadata from https://rubygems.org/.........
Fetching version metadata from https://rubygems.org/..
Fetching dependency metadata from https://rubygems.org/.
Fetching i18n 0.8.0
Installing i18n 0.8.0
Fetching json 1.8.6
Installing json 1.8.6 with native extensions
Using minitest 5.10.1
Fetching thread_safe 0.3.5
Installing thread_safe 0.3.5
Fetching addressable 2.4.0
Installing addressable 2.4.0
Using bundler 1.15.4
Using colorator 1.1.0
Fetching colorize 0.8.1
Installing colorize 0.8.1
Fetching ffi 1.9.17
Installing ffi 1.9.17 with native extensions
Using forwardable-extended 2.6.0
Fetching gemoji 3.0.0
Installing gemoji 3.0.0
Fetching mini_portile2 2.1.0
Installing mini_portile2 2.1.0
Using mercenary 0.3.6
Fetching parallel 1.12.0
Installing parallel 1.12.0
Fetching yell 2.0.7
Installing yell 2.0.7
Fetching sass 3.4.23
Installing sass 3.4.23
Fetching rb-fsevent 0.9.8
Installing rb-fsevent 0.9.8
Fetching kramdown 1.13.2
Installing kramdown 1.13.2
Fetching liquid 3.0.6
Installing liquid 3.0.6
Fetching rouge 1.11.1
Installing rouge 1.11.1
Using safe_yaml 1.0.4
Fetching posix-spawn 0.3.13
Installing posix-spawn 0.3.13 with native extensions
Fetching jekyll-paginate 1.1.0
Installing jekyll-paginate 1.1.0
Fetching tzinfo 1.2.2
Installing tzinfo 1.2.2
Fetching jekyll-sitemap 0.11.0
Installing jekyll-sitemap 0.11.0
Fetching ethon 0.10.1
Installing ethon 0.10.1
Fetching rb-inotify 0.9.8
Installing rb-inotify 0.9.8
Using pathutil 0.14.0
Fetching nokogiri 1.7.0.1
Installing nokogiri 1.7.0.1 with native extensions
Using jekyll-sass-converter 1.5.0
Fetching activesupport 4.2.7.1
Installing activesupport 4.2.7.1
Fetching typhoeus 0.8.0
Installing typhoeus 0.8.0
Using listen 3.0.8
Fetching html-pipeline 2.5.0
Installing html-pipeline 2.5.0
Fetching html-proofer 3.7.3
Installing html-proofer 3.7.3
Using jekyll-watch 1.5.0
Fetching jekyll 3.2.1
Installing jekyll 3.2.1
Fetching jekyll-last-modified-at 1.0.0
Installing jekyll-last-modified-at 1.0.0
Fetching jekyll-mentions 1.1.3
Installing jekyll-mentions 1.1.3
Fetching jekyll-redirect-from 0.11.0
Installing jekyll-redirect-from 0.11.0
Fetching jemoji 0.8.0
Installing jemoji 0.8.0
Bundle complete! 9 Gemfile dependencies, 41 gems now installed.
Use `bundle info [gemname]` to see where a bundled gem is installed.
Post-install message from html-pipeline:
$ bundle exec jekyll --version
jekyll 3.2.1

Development

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

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

$ cd xpack.github.io-source.git
$ bundle exec jekyll serve --baseurl "" --destination _site_local --trace --port 4002

The build result is in _site_local.

To view the result, point the browser to localhost:4002.

Publish

$ cd xpack.github.io-source.git
$ bundle exec jekyll build --destination "../xpack.github.io.git"

The build result is in the xpack.github.io.git folder.

To publish, commit this Git and the new site will be automatically updated.

Updates

When new versions of Jekyll, or of gems, are available, run bundle update and be sure the Gemfile.lock file is committed:

$ cd xpack.github.io-source.git
$ bundle update
The latest bundler is 1.16.0.pre.2, but you are currently running 1.15.4.
To update, run `gem install bundler --pre`
Fetching gem metadata from https://rubygems.org/..........
Fetching version metadata from https://rubygems.org/..
Fetching dependency metadata from https://rubygems.org/.
Resolving dependencies...
Fetching i18n 0.8.6 (was 0.8.0)
Installing i18n 0.8.6 (was 0.8.0)
Fetching minitest 5.10.3 (was 5.10.1)
Installing minitest 5.10.3 (was 5.10.1)
Fetching thread_safe 0.3.6 (was 0.3.5)
Installing thread_safe 0.3.6 (was 0.3.5)
Using addressable 2.4.0
Using bundler 1.15.4
Using colorator 1.1.0
Using colorize 0.8.1
Using ffi 1.9.18 (was 1.9.17)
Using forwardable-extended 2.6.0
Using gemoji 3.0.0
Fetching mini_portile2 2.3.0 (was 2.1.0)
Installing mini_portile2 2.3.0 (was 2.1.0)
Using mercenary 0.3.6
Using parallel 1.12.0
Using yell 2.0.7
Using rb-fsevent 0.10.2 (was 0.9.8)
Using kramdown 1.15.0 (was 1.13.2)
Using liquid 3.0.6
Using rouge 1.11.1
Using safe_yaml 1.0.4
Using posix-spawn 0.3.13
Using jekyll-paginate 1.1.0
Fetching tzinfo 1.2.3 (was 1.2.2)
Installing tzinfo 1.2.3 (was 1.2.2)
Using jekyll-sitemap 0.11.0
Using ethon 0.10.1
Using rb-inotify 0.9.10 (was 0.9.8)
Using pathutil 0.14.0
Fetching nokogiri 1.8.1 (was 1.7.0.1)
Installing nokogiri 1.8.1 (was 1.7.0.1) with native extensions
Fetching activesupport 4.2.10 (was 4.2.7.1)
Installing activesupport 4.2.10 (was 4.2.7.1)
Using typhoeus 0.8.0
Using sass-listen 4.0.0
Using listen 3.0.8
Fetching html-pipeline 2.7.1 (was 2.5.0)
Installing html-pipeline 2.7.1 (was 2.5.0)
Using html-proofer 3.7.3
Using sass 3.5.1 (was 3.4.23)
Using jekyll-watch 1.5.0
Using jekyll-sass-converter 1.5.0
Using jekyll 3.2.1
Using jekyll-last-modified-at 1.0.0
Using jekyll-mentions 1.1.3
Using jekyll-redirect-from 0.11.0
Fetching jemoji 0.8.1 (was 0.8.0)
Installing jemoji 0.8.1 (was 0.8.0)
Bundle updated!

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

Folder structure

Posts

All blog posts are in the _posts folder.

Pages

All web pages are in the pages folder.

'last_modified_at:'

To maintain sitelink.xml usefulness, while maintaining pages and posts, it is necessary to keep this variable up-to-date. When the pages are generated off-line, this field is automatically updated by a plug-in.

Timezone

As per _config.yml, the default timezone is UTC. For other timezones, set it explicitly as offset (for example +0300)

Images

The embedded images are located in the /assets/images folder.

For a certain degree of portability, the recommended editable format is PPTX. On macOS, PPTX files can be processed with Keynote, although saving can be done only indirectly via Export To, not directly via Save.

The preferred format is PNG. The available width is lower than 700 px, but apparently Jekyll scales images properly. By default Keynote exports images as 1024 x 768, which is generally ok for regular (non-HiRes) screens.