Document

Overview

New features, or changes to existing features, should be documented by the developer.

Process

The MeTL Website is authored in a combination of Markdown and HTML, and served by GitHub Pages (from the /docs directory in the master repo).

Consistency

When adding a new page, consider adding it to /sitemap.xml for Google Search indexing, and to /_includes/nav.html or /_includes/nav-guide.html as appropriate.

Local Jekyll

GitHub Pages uses Jekyll to convert Markdown into HTML, and this can be emulated locally.

gem install jekyll
gem install bundler
gem install minima
gem install jekyll-feed
gem install public_suffix
gem install addressable
gem install kramdown

bundle install

To run a local Jekyll server on port 4000 that watches for changed files:

./jekyll.sh

Gem install failure

If you get a Gem install failure:

SSL_connect returned=1 errno=0 state=SSLv3 read server certificate B: certificate verify failed

This error is produced by changes in rubygems.org infrastructure, please keep reading to better understand it.

Download rubygems_update version 2.6.8 (latest version at this time)

Install rubygems_update:

gem install rubygems-update-2.6.8.gem

Run it:

update_rubygems --no-ri --no-rdoc

Make sure gem -v returns version 2.6.8

[Optional] Uninstall rubygems_update:

gem uninstall rubygems-update -x