Skip to content

Latest commit

 

History

History
124 lines (89 loc) · 6.53 KB

README.md

File metadata and controls

124 lines (89 loc) · 6.53 KB
Raw

CWL Website - Instructions

Instructions on how to run and edit the main commonwl.org website.

See the main README.md for general instructions on contributing. See the Security Policy page to report a vulnerability.

Table of Contents:

Setup & Development

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:

Running the Site Locally

After installing the prerequisite software, in your terminal:

  1. cd content/
  2. bundle exec jekyll serve --config "_config.yml,_config_local.yml" (note the lack of spaces between the two config files).
  3. In your browser, type localhost in your address bar, to view the site.

It's important to specify both config files, in order. Otherwise Jekyll will generate the site's urls with commonwl.org, and you won't be able to run it locally.

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

Use a custom url or port: For convenience, you may wish to specify --host cwl.test and --port 80 (or any other value), 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 custom url.

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

Important Files and Directories

The directories for the main website look something like this:

├── _data
├── _includes
│   └── home
├── _layouts
├── _plugins
├── _sass
│   ├── bootstrap
│   └── partials
│       └── home
├── assets
│   ├── img
│   ├── js
│   ├── plyr
│   └── video
│       └── subtitles
│           └── srt
└── favicon

Important directories:

  • _data - holds the data for: nav menus, timeline, and user galleries
  • _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

Config Files

The site uses the following config files:

  • _config.yml - for the production site
  • _config_local.yml - for local development

If you make changes to _config_local.yml, please don't commit them to the repo. Prior to making any changes, run 'git update-index --skip-worktree _config_local.yml 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 afterwards, to retrieve it).

Editing the Site - General Flow

  1. On the main branch, run 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. Create a new branch (git checkout -b branch-name-here) or checkout an existing branch (git checkout branch-name-here) to work on your updates. Note: leaving out the -b ensures that git knows to track the remote branch.
  4. Commit your changes, and then git push origin branch-name-here
  5. Create a pull request from your branch on the CWL Website Repo (the URL should look like https://github.com/common-workflow-language/cwl-website/tree/branch-name-here)

Editing Guidelines

Instructions and guidelines for editing specific parts of the site can be found in EDITING.md

User Gallery Nomination

To suggest a new entry for the CWL User Gallery, create a new Issue, with the following template: https://github.com/common-workflow-language/cwl-website/issues/new?assignees=&labels=user+gallery&template=user-gallery-nomination.md&title=User+Gallery+Nomination%3A+%5Buser%2Fproject+name+here%5D

Reporting a Vulnerability

See the Security Policy page.