diff --git a/README.md b/README.md index 4ac88e3..149f2e3 100644 --- a/README.md +++ b/README.md @@ -1,101 +1,127 @@ # ClusterLabs.org website ## Installing Jekyll ClusterLabs,org is partially generated by jekyll. Installing jekyll requires the following dependencies: * nodejs * npm * ruby * ruby-devel * rubygems * rubygem-bundler * rubygem-rdiscount Once you have those, change to the `src` directory and run `bundle install`. ## Using Jekyll ClusterLabs.org's jekyll source is under the `src` directory. Jekyll will generate static content to the html directory. To generate content in a checkout for development and testing, change to the `src` directory and run `bundle exec jekyll build` (to merely generate content) or `bundle exec jekyll serve` (to generate and test via a local server). To generate content on the production site, run -`JEKYLL_ENV=production jekyll build` (which will enable such things as asset -digests). +`JEKYLL_ENV=production bundle exec jekyll build` (which will enable such things +as asset digests). If `src/Gemfile` changes, re-run `bundle install` afterward. +### Updating Ruby gems + +Display Ruby dependencies, with their current version: + + bundle list + +Show available updates: + + bundle outdated + +Show where a gem comes from: + + bundle info $GEM + +Update one gem and dependencies (will update Gemfile.lock, which must be committed): + + bundle update $GEM + +If a gem can't update due to not supporting the local Ruby version or +installable versions of other gems, you can edit Gemfile or Gemfile.lock to add +a version restriction like: + + gem-name (2.7.0) -> exact version + gem-name (>= 2.0.2, < 5.0) -> version within range + gem-name.rb (~> 0.6.0) -> last number may increase + ## Images, stylesheets and JavaScripts We use the jekyll-assets plugin to manage "assets" such as images, stylesheets, and JavaScript. One advantage is that digest hashes are automatically added to the generated filenames when in production mode. This allows "cache busting" when an asset changes, so we can use long cache times on the server end. Another advantage is that sources are minified when in production mode. How CSS is managed: * CSS is generated from SASS sources * `src/_assets/stylesheets/main.scss` is just a list of imports * all other *.scss files beneath `src/_assets/stylesheets` contain the SASS to be imported by `main.scss` * jekyll will generate `html/assets/main.css` (or `main-_HASH_.css`) as the combination of all imports * web pages can reference the stylesheet via `{% stylesheet main %}` JavaScript is managed similarly: * `src/_assets/javascripts/main.js` is just a list of requires * `src/_assets/javascripts/*.js` contain the JavaScript to be required by `main.js` * jekyll will copy these to `html/assets` * jekyll will generate `html/assets/main.js` (or `main-_HASH_.js`) as the combination of all JavaScript * web pages can reference the script via `{% javascript main %}` How images are managed: * `src/_assets/images/*` are our images * web pages can add an img tag using `{% image _NAME_._EXT_ %}` * web pages can reference a path to an image (e.g. in a link's href) using `{% asset_path _NAME_._EXT_ %}` * CSS can reference a path to an image using `url(asset_path("_NAME_._EXT_"))` * only images that are referenced in one of these ways will be deployed to the website, so `_assets` may contain image sources such as SVGs that do not need to be deployed * Tip: http://compresspng.com/ can often compress PNGs extremely well ## Site icons Site icons used to be easy, right? `favicon.ico` seems downright traditional. Unfortunately, site icons have become an ugly mess of incompatible proprietary extensions. Even `favicon.ico` is just a proprietary extension (and obsolete, as well). Now, there are also `apple-touch-icon[-NxN][-precomposed].png` (with at least _12_ different sizes!), `browserconfig.xml`, `manifest.json`, link tags with `rel=(icon|shortcut icon|apple-touch-icon-*)`, and Windows Phone tile overlay divs. If you want to be discouraged and confused, see: * http://stackoverflow.com/questions/23849377/html-5-favicon-support * https://mathiasbynens.be/notes/touch-icons * https://css-tricks.com/favicon-quiz/ There is no way to handle the mess universally. In particular, some devices do much better when different icon sizes are provided and listed in the HTML as link tags, and will pick the size needed, whereas other devices will download every single icon listed in those link tags, crippling page performance -- not to mention the overhead that listing two dozen icon sizes adds to the HTML. We've chosen a simple approach: provide two site icons, a 16x16 `favicon.ico`, and a 180x180 `apple-touch-icon.png`, both listed in link tags in the HTML. Most browsers/devices will choose one of these and scale it as needed. ## Web server configuration The clusterlabs.org web server is configured to redirect certain old URLs to their new locations, so be careful about renaming files. diff --git a/src/Gemfile b/src/Gemfile index afc5081..08f8d58 100644 --- a/src/Gemfile +++ b/src/Gemfile @@ -1,35 +1,40 @@ source "https://rubygems.org" ruby RUBY_VERSION # Hello! This is where you manage which Jekyll version is used to run. # When you want to use a different version, change it below, save the # file and run `bundle install`. Run Jekyll with `bundle exec`, like so: # # bundle exec jekyll serve # # This will help ensure the proper Jekyll version is running. # Happy Jekylling! -gem "jekyll" + +# jekyll-assets does not support jekyll 4 yet +gem "jekyll", "~> 3.0" # This is the default theme for new Jekyll sites. You may change this to anything you like. gem "minima", "~> 2.0" +# not sure why jekyll doesn't generate this dependency automatically +gem "kramdown-parser-gfm" + # Needed by jekyll-assets group :jekyll_assets_deps do gem "public_suffix" gem "ruby_dep" gem "rb-inotify" gem "listen" gem "jekyll-watch" gem "json" end # If you want to use GitHub Pages, remove the "gem "jekyll"" above and # uncomment the line below. To upgrade, run `bundle update github-pages`. # gem "github-pages", group: :jekyll_plugins # If you have any plugins, put them here! group :jekyll_plugins do - gem "jekyll-assets" + gem "jekyll-assets", "~> 2.0" gem "font-awesome-sass" end diff --git a/src/Gemfile.lock b/src/Gemfile.lock index 1b58877..7bc311c 100644 --- a/src/Gemfile.lock +++ b/src/Gemfile.lock @@ -1,121 +1,107 @@ GEM remote: https://rubygems.org/ specs: - addressable (2.7.0) + addressable (2.8.0) public_suffix (>= 2.0.2, < 5.0) colorator (1.1.0) - concurrent-ruby (1.1.6) - em-websocket (0.5.1) + concurrent-ruby (1.1.9) + em-websocket (0.5.2) eventmachine (>= 0.12.9) http_parser.rb (~> 0.6.0) eventmachine (1.2.7) - fastimage (1.8.1) - addressable (~> 2.3, >= 2.3.5) - ffi (1.12.2) - font-awesome-sass (5.12.0) + extras (0.3.0) + forwardable-extended (~> 2.5) + fastimage (2.2.4) + ffi (1.15.3) + font-awesome-sass (5.15.1) sassc (>= 1.11) forwardable-extended (2.6.0) - hike (1.2.3) http_parser.rb (0.6.0) - i18n (1.8.2) + i18n (0.9.5) concurrent-ruby (~> 1.0) - jekyll (4.0.0) + jekyll (3.9.1) addressable (~> 2.4) colorator (~> 1.0) em-websocket (~> 0.5) - i18n (>= 0.9.5, < 2) - jekyll-sass-converter (~> 2.0) + i18n (~> 0.7) + jekyll-sass-converter (~> 1.0) jekyll-watch (~> 2.0) - kramdown (~> 2.1) - kramdown-parser-gfm (~> 1.0) + kramdown (>= 1.17, < 3) liquid (~> 4.0) mercenary (~> 0.3.3) pathutil (~> 0.9) - rouge (~> 3.0) + rouge (>= 1.7, < 4) safe_yaml (~> 1.0) - terminal-table (~> 1.8) - jekyll-assets (1.0.0) - fastimage (~> 1.6) - jekyll (>= 2) - mini_magick (~> 4.1) - sass (~> 3.2) - sprockets (~> 2.10) - sprockets-helpers - sprockets-sass - jekyll-feed (0.13.0) + jekyll-assets (2.4.0) + concurrent-ruby (~> 1.0) + extras (~> 0.2) + fastimage (~> 2.0, >= 1.8) + jekyll (~> 3.1, >= 3.0) + pathutil (>= 0.8) + rack (~> 1.6) + sprockets (~> 3.3, < 3.8) + jekyll-feed (0.15.1) jekyll (>= 3.7, < 5.0) - jekyll-sass-converter (2.1.0) - sassc (> 2.0.1, < 3.0) - jekyll-seo-tag (2.6.1) - jekyll (>= 3.3, < 5.0) + jekyll-sass-converter (1.5.2) + sass (~> 3.4) + jekyll-seo-tag (2.7.1) + jekyll (>= 3.8, < 5.0) jekyll-watch (2.2.1) listen (~> 3.0) - json (2.3.0) + json (2.5.1) kramdown (2.3.1) rexml kramdown-parser-gfm (1.1.0) kramdown (~> 2.0) liquid (4.0.3) - listen (3.2.1) + listen (3.5.1) rb-fsevent (~> 0.10, >= 0.10.3) rb-inotify (~> 0.9, >= 0.9.10) mercenary (0.3.6) - mini_magick (4.10.1) minima (2.5.1) jekyll (>= 3.5, < 5.0) jekyll-feed (~> 0.9) jekyll-seo-tag (~> 2.1) - multi_json (1.15.0) pathutil (0.16.2) forwardable-extended (~> 2.6) - public_suffix (4.0.4) + public_suffix (4.0.6) rack (1.6.13) - rb-fsevent (0.10.3) + rb-fsevent (0.11.0) rb-inotify (0.10.1) ffi (~> 1.0) rexml (3.2.5) - rouge (3.18.0) + rouge (3.26.0) ruby_dep (1.5.0) safe_yaml (1.0.5) sass (3.7.4) sass-listen (~> 4.0.0) sass-listen (4.0.0) rb-fsevent (~> 0.9, >= 0.9.4) rb-inotify (~> 0.9, >= 0.9.7) - sassc (2.2.1) + sassc (2.4.0) ffi (~> 1.9) - sprockets (2.12.5) - hike (~> 1.2) - multi_json (~> 1.0) - rack (~> 1.0) - tilt (~> 1.1, != 1.3.0) - sprockets-helpers (1.2.3) - sprockets (>= 2.2) - sprockets-sass (1.3.1) - sprockets (~> 2.0) - tilt (~> 1.1) - terminal-table (1.8.0) - unicode-display_width (~> 1.1, >= 1.1.1) - tilt (1.4.1) - unicode-display_width (1.7.0) + sprockets (3.7.2) + concurrent-ruby (~> 1.0) + rack (> 1, < 3) PLATFORMS ruby DEPENDENCIES font-awesome-sass - jekyll - jekyll-assets + jekyll (~> 3.0) + jekyll-assets (~> 2.0) jekyll-watch json + kramdown-parser-gfm listen minima (~> 2.0) public_suffix rb-inotify ruby_dep RUBY VERSION - ruby 2.5.5p157 + ruby 2.5.9p229 BUNDLED WITH 1.16.1 diff --git a/src/_config.yml b/src/_config.yml index 8655537..991dcc9 100644 --- a/src/_config.yml +++ b/src/_config.yml @@ -1,48 +1,48 @@ # Welcome to Jekyll! # # This config file is meant for settings that affect your whole blog, values # which you are expected to set up once and rarely edit after that. If you find # yourself editing these this file very often, consider using Jekyll's data files # feature for the data you need to update frequently. # # For technical reasons, this file is *NOT* reloaded automatically when you use # 'bundle exec jekyll serve'. If you change this file, please restart the server process. # Site settings # These are used to personalize your new site. If you look in the HTML files, # you will see them accessed via {{ site.title }}, {{ site.email }}, and so on. # You can create any custom variable you would like, and they will be accessible # in the templates via {{ site.myvariable }}. title: ClusterLabs email: users@clusterlabs.org description: Community hub for open-source high-availability software url: https://www.clusterlabs.org/ # Build settings theme: minima destination: ../html -gems: +plugins: - jekyll-assets - font-awesome-sass include: - doc - pacemaker - polls exclude: - Gemfile - Gemfile.lock - LICENSE.theme # All content generated outside of jekyll, or not yet converted to jekyll, # must be listed here, or jekyll will erase it when building the site. # Though not documented as such, the values here function as prefix matches. keep_files: - images - doc/Two-Stacks.pdf - pacemaker/abi - pacemaker/doc - pacemaker/doxygen - pacemaker/global - pacemaker/man