/cwl-website

www.commonwl.org

Primary LanguageJavaScriptApache License 2.0Apache-2.0

Common Workflow Language Website 2.0

This is the repo for the CWL Website.

Prerequisites

You need the following in order to run the site:

  • Ruby version 2.4.0 or higher, including all development headers (check your Ruby version using ruby -v)
  • RubyGems (check your Gems version using gem -v)
  • GCC and Make (check versions using gcc -v,g++ -v, and make -v)

For Ruby, you may need additional developer packages(e.g. ruby-dev, ruby-bundler). See the following links, for detailed instructions:

Project & Directory Structure

The root directory contains the following important files and directories:

  • content - directory for the main website
  • README.md - general readme for the repo.
  • site - directory for the Docs. Not the main site
  • STAGING - instructions for the staging site.
  • website.sh - script that builds the website

Main Website

The main website (https://www.commonwl.org/) is generated via Jekyll. The files for it are found in /content, and the directories should look something like this

├── _data
├── _includes
│   └── home
├── _layouts
├── _sass
│   ├── bootstrap
│   │   ├── mixins
│   │   ├── utilities
│   │   └── vendor
│   └── partials
├── _subtitles
├── assets
│   ├── css
│   ├── img
│   ├── js
│   ├── plyr
│   └── video
│       └── subtitles
└── favicon
  • _data - includes the data for the two nav menus
  • _includes - the templates for the site sections. Each homepage section has its own sub-template under _includes/home
  • _sass - the scss styles for the entire site. The bootstrap should be left alone.
  • assets - contains the various images, scripts, video subtitles, etc.
  • favicon - contains the favicon files for various browsers, generated by RealFaviconGenerator

Running the Site

After installing the prerequisite software, in your terminal cd content/, and run bundle exec jekyll serve --config "_config.yml,_config_local.yml" (note the lack of spaces between the two config files). You can then open up localhost in your web browser to view the site. It's important to specify the config files, as otherwise Jekyll will generate the site's urls with commonwl.org, and you won't be able to run it locally.

If you receive an error message about software dependencies, packages, gems, etc, then run bundle update from the content directory. (Bundlr will be looking for Gemfile and Gemfile.lock, and can't run without them).

For convenience, you may wish to specify --host cwl.test and --port 80, as follows: bundle exec jekyll serve --config "_config.yml,_config_local.yml --host cwl.test --port 80. NOTE: you may have to update your hosts file, in order for your computer to respect the hostname.

Anything you specify on the command line wil override the settings in your config files. For a full list of command line options, see Jekyll - Configuration Options Serve Commands and Build Commands

Editing the Site - General Flow

  1. On main, run a git fetch --all to see which branches have been updated.
  2. Run git pull origin main to pull in any changes from the production site.
  3. Switch to add-jekyll-site and then merge the changes via git merge main
  4. Make sure you're making your changes on the add-jekyll-site (or your own branch, which you can merge to add-jekyll-site).
  5. Push to add-jekyll-site and then check that everything looks good.
  6. If all is well, head over to the main repo and create a Pull Request.

Config Files & Local Development

The site uses the following config files:

  • _config.yml - for the production site
  • _config_local.yml - for local development
  • _config_staging.yml - for the staging site (only appears in add-jekyll-site branch)

If you make changes to _config_local.yml, please don't commit them to the repo. If you run into an issue with switching branches (you can run git stash or git stash push _config_local.yml before committing, and then git stash pop after, to retrieve it).

Video Player - Plyr

The video player is built using Plyr. The scripts for it are found in assets/plyr, and shouldn't really be touched.

The HTML and JS that renders the video player is found in _includes/home/video-player.html. The additional styles for the video player are in _sass/partials/home.scss.

Subtitles are found in assets/video/subtitles, and were extracted from the original YouTube video via DownSub, and converted to .vtt via Subtitle Tools - Convert Subtitles to Vtt.

Plyr API options

controls: [
    'play-large', // The large play button in the center
    'restart', // Restart playback
    'rewind', // Rewind by the seek time (default 10 seconds)
    'play', // Play/pause playback
    'fast-forward', // Fast forward by the seek time (default 10 seconds)
    'progress', // The progress bar and scrubber for playback and buffering
    'current-time', // The current time of playback
    'duration', // The full duration of the media
    'mute', // Toggle mute
    'volume', // Volume control
    'captions', // Toggle captions
    'settings', // Settings menu
    'pip', // Picture-in-picture (currently Safari only)
    'airplay', // Airplay (currently Safari only)
    'download', // Show a download button with a link to either the current source or a custom URL you specify in your options
    'fullscreen', // Toggle fullscreen
];

Twitter Feed

The twitter feed code is found in _includes/twitter_feed.html. It includes the data-dnt attribute, so as not to track user data. Despite this, the feed won't render on many mobile devices, due to default privacy settings in Chrome and Firefox. In that case the users will simply see "See Tweets by @commonwl", in place of the feed itself.

SEO Tags

The SEO meta for the site is auto-generated via jekyll-seo-tag. See Jekyll SEO Tag - Usage for reference.