This GitHub project, available from micro-os-plus/micro-os-plus.github.io-source, contains the source files used to generate the µOS++ web site.
The µOS++ web site is an organisation GitHub Pages site, stored in the micro-os-plus/micro-os-plus.github.io Git and publicly available from http://micro-os-plus.github.io.
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.
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 preinstalled, at least when the Developer Command Line tools are present.
If you are like me and like really separated things, install a separate homebrew instance only for the jekyll builds.
$ HB_PREFIX="/opt/homebrew-jekyll3"
$ echo 'Enter sudo password'
$ sudo rm -rf "${HB_PREFIX}"
$ sudo mkdir -p "${HB_PREFIX}"
$ sudo bash -c "(curl -L https://github.com/Homebrew/homebrew/tarball/master | tar -x -v --strip 1 -C "${HB_PREFIX}" -f -)"
$ "${HB_PREFIX}/bin/brew" --version
$ "${HB_PREFIX}/bin/brew" update
$ alias hbj3='export PATH=/opt/homebrew-jekyll3/bin:$PATH'
$ hbj3
$ sudo brew install ruby
The result is in /opt/homebrew-jekyll3/Cellar/ruby/2.3.1
$ ruby --version
ruby 2.3.1p112 (2016-04-26 revision 54768) [x86_64-darwin15]
$ gem --version
2.5.1
$ sudo gem install bundler
Fetching: bundler-1.12.5.gem (100%)
Successfully installed bundler-1.12.5
Parsing documentation for bundler-1.12.5
Installing ri documentation for bundler-1.12.5
Done installing documentation for bundler after 7 seconds
1 gem installed
$ bundler --version
Bundler version 1.12.5
To manage the web site, a local copy of this repository is required.
git clone https://github.com/micro-os-plus/micro-os-plus.github.io-source.git micro-os-plus.github.io-source.git
git clone https://github.com/micro-os-plus/micro-os-plus.github.io.git micro-os-plus.github.io.git
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 micro-os-plus.github.io-source.git
$ sudo bundle install
Fetching gem metadata from https://rubygems.org/
Fetching version metadata from https://rubygems.org/
Fetching dependency metadata from https://rubygems.org/
Resolving dependencies...
Using i18n 0.7.0
Using json 1.8.3
Installing minitest 5.9.0
Using thread_safe 0.3.5
Installing addressable 2.4.0
Installing colorator 1.1.0
Installing ffi 1.9.14 with native extensions
Installing forwardable-extended 2.6.0
Using gemoji 2.1.0
Using mini_portile2 2.1.0
Using pkg-config 1.1.7
Using sass 3.4.22
Using rb-fsevent 0.9.7
Using kramdown 1.11.1
Using liquid 3.0.6
Using mercenary 0.3.6
Using rouge 1.11.1
Using safe_yaml 1.0.4
Using jekyll-paginate 1.1.0
Using bundler 1.12.5
Using tzinfo 1.2.2
Installing jekyll-sitemap 0.11.0
Using rb-inotify 0.9.7
Installing pathutil 0.14.0
Using nokogiri 1.6.8
Using jekyll-sass-converter 1.4.0
Installing activesupport 4.2.7.1
Using listen 3.0.8
Installing html-pipeline 2.4.2
Installing jekyll-watch 1.5.0
Installing jekyll 3.2.1
Using jekyll-last-modified-at 0.3.4
Installing jekyll-mentions 1.1.3
Installing jekyll-redirect-from 0.11.0
Installing jemoji 0.7.0
Bundle complete! 7 Gemfile dependencies, 35 gems now installed.
Use `bundle show [gemname]` to see where a bundled gem is installed.
$ bundle exec jekyll --version
jekyll 3.2.1
The current development cycle is edit-save-build-view.
The build can be performed automatically by Jekyll when started in server mode.
cd micro-os-plus.github.io-source.git
bundle exec jekyll serve --baseurl "" --destination _site_local --trace --port 4001
The build result is in _site_local
.
To view the result, point the browser to localhost:4001
.
cd micro-os-plus.github.io-source.git
bundle exec jekyll build --destination ../micro-os-plus.github.io.git
The build result is in the micro-os-plus.github.io.git
folder.
To publish, commit this Git and the new site will be automatically updated.
When new versions of Jekyll, or of gems, are available, run bundle update
and be sure the Gemfile.lock
file is committed:
$ cd micro-os-plus.github.io-source.git
$ sudo bundle update
Fetching gem metadata from https://rubygems.org/
Fetching version metadata from https://rubygems.org/
Fetching dependency metadata from https://rubygems.org/
Resolving dependencies...
Using i18n 0.7.0
Using json 1.8.3
Using minitest 5.9.0
Using thread_safe 0.3.5
Using addressable 2.4.0
Using colorator 1.1.0
Using ffi 1.9.14
Using forwardable-extended 2.6.0
Using gemoji 2.1.0
Using mini_portile2 2.1.0
Using pkg-config 1.1.7
Using sass 3.4.22
Using rb-fsevent 0.9.7
Using kramdown 1.11.1
Using liquid 3.0.6
Using mercenary 0.3.6
Using rouge 1.11.1
Using safe_yaml 1.0.4
Using jekyll-paginate 1.1.0
Using bundler 1.12.5
Using tzinfo 1.2.2
Using jekyll-sitemap 0.11.0
Using rb-inotify 0.9.7
Using pathutil 0.14.0
Using nokogiri 1.6.8
Using jekyll-sass-converter 1.4.0
Using activesupport 4.2.7.1
Using listen 3.0.8
Using html-pipeline 2.4.2
Using jekyll-watch 1.5.0
Using jekyll 3.2.1
Using jekyll-last-modified-at 0.3.4
Using jekyll-mentions 1.1.3
Using jekyll-redirect-from 0.11.0
Using jemoji 0.7.0
Bundle updated!
People using forked repositories must run bundle install
to be sure the required versions are properly installed.
All blog posts are in the _posts
folder.
All web pages are in the pages
folder.
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.
As per _config.yml
, the default timezone is UTC. For other timezones, set it explicitly as offset (for example +0300)
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.