Page MenuHomeClusterLabs Projects
Files F1841326

README.md
No OneTemporary
Actions

README.md
View Options

# ClusterLabs.org website
## Installing Jekyll
ClusterLabs.org is partially generated by Jekyll, a Ruby gem. The following
dependencies are required by Jekyll:
* nodejs
* npm
* Ruby
* Bundler
See src/Gemfile.lock for the currently required versions of those dependencies.
Once you have these four dependencies, install Jekyll by changing to the `src`
directory and running `bundle install`.
Note: If your development environment is not lucky enough to have the required
versions, these instructions might help:
* Install Ruby Version Manager and its dependencies:
* `sudo dnf install rvm gcc g++ zlib-devel autoconf`
* Then, use rvm to install OpenSSL and the desired Ruby version:
* `rvm pkg install openssl`
* `rvm install $RUBY_VERSION --rubygems $GEMS_VERSION --with-openssl-dir=$HOME/.rvm/usr`
* `rvm use $RUBY_VERSION`
* Then, use gem to install the desired version of any gems.
* `gem install $GEM_NAME:$GEM_VERSION`
## 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 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, or you need to raise a dependency version
to fix a security issue, you can edit Gemfile to add a version restriction
like:
gem "gem-name", "2.7.0" -> exact version
gem "gem-name", ">= 2.0.2, < 5.0" -> version within range
gem "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.

File Metadata

Mime Type
text/plain
Expires
Sat, Nov 23, 3:14 AM (48 m, 41 s)
Storage Engine
blob
Storage Format
Raw Data
Storage Handle
1018097
Default Alt Text
README.md (5 KB)

Event Timeline