Jekyll-hosted websites

A number of OME websites are produced using Jekyll, including:

These sites can be built and tested by installing a local copy of Jekyll. The Help and Figure sites are also built by CI jobs, see Documentation jobs.

The publicly released pages are hosted and automatically generated by GitHub Pages with a custom subdomain.

Installing Jekyll

Jekyll can be installed as a system application (requires administrator privileges) or for a single user.

  1. Install a recent version of Ruby. Recent versions of OS X and Linux may already include a suitable version, however you will require administrator privileges to install Jekyll. Alternatively on OS X you can use Homebrew, and on Linux either rbenv or RVM:

    brew install ruby
    
  2. Install Jekyll:

    gem install jekyll
    

Running Jekyll

In a terminal enter the local git checkout and run:

jekyll serve -w -b ''

This will build the web pages and start a local server on http://localhost:4000/. Jekyll should automatically rebuild the pages when changes are made to the source files, and will override any baseurl defined in _config.yml.

Editing the websites

Main OME Website

The source for the OME Website is on GitHub at https://github.com/ome/www.openmicroscopy.org. The website uses the ‘master’ branch, PRs should be opened directly against it. Most of the files are written in html but the announcements posts are in markdown and further content may migrate to markdown in future.

Once a PR is open and has passed Travis, it will be integrated in the staging integration branch for the OME Website site via the daily WEBSITE-push job. The staging Jekyll website will be deployed by the GitHub Pages service at https://snoopycrimecop.github.io/www.openmicroscopy.org for review.

Once the PR is merged, the HEAD of master will be deployed by the GitHub pages service at https://ome.github.io/www.openmicroscopy.org.

Updating the live website requires two steps, first creating an archive of the static website and then deploying it on the web server:

  • to release the Jekyll source code, a signed Git tag needs to be created from the master branch of the source code. Website tags must follow the [Calendar Versioning](https://calver.org/#youtube-dl) scheme using the tag date

  • after pushing the tag, an artifact of the static website will be built by [GitHub Actions](https://github.com/ome/www.openmicroscopy.org/actions) and deployed as an asset of the associated GitHub release

  • to update the static website, either the sudo deploy -f command should be executed from the OME website server or the full www Ansible playbook can be executed.

OME Blog

The source for blog.openmicroscopy.org is at https://github.com/ome/blog. The website uses the ‘gh-pages’ branch and as there is no merge build or staging page, you should open a PR directly against this branch. The files are written in markdown. Branches must be built locally for review and merging PRs automatically updates the live site.