The C4 User Website

This repository contains the C4 user website. Updates to the 'master' branch will be published and go live within one minute.

Prototype the website locally

To get a local copy of this repos, do:

$ cd /path/to/my/repositories
$ git clone https://github.com/UCSF-CBI/c4.git
$ cd c4
$ pwd
/path/to/my/repositories/c4

To launch a localhost instance of the website, do:

$ ## Make sure to have 'bundle' on the PATH, e.g.
$ ## export PATH="$HOME/.gem/ruby/2.5.0/bin:$PATH"

$ cd docs
$ bundle exec jekyll serve --port 4001
Configuration file: /home/alice/c4/docs/_config.yml
            Source: /home/alice/c4/docs
       Destination: /home/alice/c4/docs/_site
 Incremental build: disabled. Enable with --incremental
      Generating... 
                    done in 0.94 seconds.
 Auto-regeneration: enabled for '/home/alice/c4/docs'
    Server address: http://127.0.0.1:4001
  Server running... press ctrl-c to stop.

and then open http://127.0.0.1:4001 in the web browser. Note that Jekyll monitors all files and if one of them is updated, then Jekyll will instantaneously re-render the corresponding HTML file. There is no need to relaunch Jekyll or by other means manually re-render files. For instance, if there has been updates made to the git repository, doing:

$ git pull

will pull down those updates locally and Jekyll will automatically re-render the HTML website.

Spell checking

$ make spell
No spelling errors found.

This requires R and that the spelling R package is installed, e.g. install.packages("spelling", repos="https://cloud.r-project.org"). If there are words that are incorrectly flagged as misspelled, they can be added to the 'docs/WORDLIST' file.

Linting

To validate the Markdown syntax and that we follow a consistent style, run:

$ make markdownlint
*** markdownlint:
[ OK ] checking ./assets/README.md
[ OK ] checking ./about/specs.md
...
[ OK ] checking ./index.md
RESULT: 50 OK, 0 ERROR

If there are errors, the explanation for them can be found on https://github.com/DavidAnson/markdownlint/blob/main/doc/Rules.md. The online markdownlint demo can be useful to better understand certain errors.

Several of the rules are disabled in the docs/.markdownlint.json configuration file.

To run these tests locally, install markdownlint-cli.

To validate the Markdown URLs exists, run:

$ make markdown-link-check
*** markdown-link-check:
[ OK ] checking ./assets/README.md
[ OK ] checking ./about/specs.md
...
[ OK ] checking ./index.md
RESULT: 50 OK, 0 ERROR

To run these tests locally, install markdown-link-check.

Technical details

This website is built upon Jekyll, where content is mostly written in Markdown and rendered by Jekyll into HTML. The user interface and its style is handled mainly by JavaScript and CSS.

• https://github.com/UCSF-CBI/c4/:

  • The source Git repository for the website

• https://ucsf-hpc.github.io/c4/:

  • The official, public website

Installing Jekyll

Warning: It turns out that the most recent version of Jekyll is not compatible with the recent version of GitHub Pages. Specifically, GitHub Pages requires Jekyll version >= 3.7.3 and < 4.0.0 - the latest version verified to work is Jekyll 3.8.7. So we need to make sure to install specific version of a few packages below.

The below instructions assumes that Ruby and its gem command is available on the machine. Other than that, making sure to use option --user-install when installing, you should be able install Jekyll to your personal account without admin rights.

$ gem install --user-install bundler jekyll:3.8.7 listen:3.1.5 liquid:4.0.0 github-pages:204
Fetching: bundler-2.1.4.gem (100%)
WARNING:  You don't have /home/alice/.gem/ruby/2.5.0/bin in your PATH,
          gem executables will not run.
Successfully installed bundler-2.1.4
Parsing documentation for bundler-2.1.4
Installing ri documentation for bundler-2.1.4
...
Installing ri documentation for liquid-4.0.0
Done installing documentation for liquid after 1 seconds
48 gems installed

That's it.

You then need to prepend $HOME/.gem/ruby/2.5.0/bin to your PATH such that the bundler command in that folder is automatically found;

$ export PATH="$HOME/.gem/ruby/2.5.0/bin:$PATH"
$ which bundle
/home/alice/.gem/ruby/2.5.0/bin/bundle

Set that PATH in your ~/.bashrc startup file to make it apply automatically.

That's it. You can now launch the website locally as above.

Licenses

• The content of the C4 is licensed under a Creative Commons Attribution-ShareAlike 4.0 International License (CC BY-SA 4.0).

• In addition to content, there are JavaScript frameworks and CSS files controlling the rendering of the webpage. See the corresponding folders for their licenses.