This is the repository for the HPC Carpentry website (and directly based on the Carpentries website). Please submit additions and fixes as pull requests to our GitHub repository.
Lessons are not stored in this repository. Please see the HPC Carpentry lessons page, for links to the many individual lesson repositories. You can find the official Carpentries lessons at the Software Carpentry lessons page, the Data Carpentry lessons page, or the Library Carpentry lessons page.
HPC Carpentry, like The Carpentries (Software, Data, and Library Carpentry), is an open project, and we welcome contributions of all kinds. By contributing, you are agreeing that The Carpentries may redistribute your work under these licenses, and to abide by our code of conduct.
The website uses Jekyll, a static website generator written in Ruby. You need to have Version 2.7.1 or higher of Ruby and the package manager Bundler. (The package manager is used to make sure you use exactly the same versions of the Ruby Gems as we do.) After checking out the repository, please install Jekyll and dependencies by running
$ bundle install
You may consult Using Jekyll with Pages for further instructions.
Please do not use jekyll build or jekyll serve directly to build or
view the website. Instead, you should use the following commands:
makeormake commands: list available commands.make data: (optionally) generate the dynamic data (see Data Files to see the requirements for this step)make serve: build files locally and run a server at http://0.0.0.0:4000/ for viewing. This is the best way to preview the site.make site: build files locally, but do not serve them dynamically.make cleanremoves the_sitedirectory and any Emacs editor backup files littering the source directories.
The details describes a few more advanced commands as well.
To write a blog post,
create a file called _posts/YYYY/MM/YYYY-MM-DD-some-title.html or
_posts/YYYY/MM/YYYY-MM-DD-some-title.md (for HTML and Markdown respectively).
YYYY is the 4-digit year of the post, MM the 2-digit month, and DD the 2-digit
day; some-title can be any hyphenated string of words that do not include
special characters such as quotes.
Please do not use underscores or periods in the names.
When published, your blog post will appear as
https://hpc-carpentry.org/blog/YYYY/MM/some-title.html.
The YAML header of a blog post must look like this:
---
layout: page
authors: ["Your Name"]
title: "A Title-Cased Title for the Post"
date: YYYY-MM-DD
time: "hh:mm:ss"
category: ["Some Category", "Some Other Category"]
---
where YYYY-MM-DD is replaced by the post's date and hh:mm:ss by the post's
time. Note that the time must be quoted so that the colons it contains do not
confuse Jekyll's YAML parser. Note also that authors is a list. If the post
has more than one author, please format the list like this:
...
authors: ["First Author", "Second Author", "Third Author"]
...
rather than running all the authors' names together in one long string.
To create a new page,
add a file to the pages directory.
This can be written in either Markdown or HTML,
and must have the following YAML header:
layout: page-fullwidth
permalink: /some/path/
title: Title in Title Case
You must then also add the page to _data/navigation.yml,
which is used to generate the site's pull-down navigation menu.
To add a workshop, fill in the workshop request form online. You should fill in this form even for self-organized workshops in order to get your workshop into the Carpentries database.
The website is built with a GitHub Action, configured in
.github/workflows/build-and-deploy.yml.
Each time a commit is pushed to the default branch of the repository (main)
and every 24 hours, the GitHub Action does the following:
- Validate the YAML headers of all the pages and blog posts.
- Update the time-dependent content (list of lessons, list of "Help Wanted" issues, etc.). For details on how these data files can be generated see the next section.
- Build and deploy the website to https://www.hpc-carpentry.org.
The data files for the workshops and the instructors are generated by our
GitHub Action using the scripts found in the feeds folder.
To generate these feeds locally,
make data
To successfully execute this step you need an appropriate R environment (with
packages colorspace, deplyr, gh, jsonlite, purrr, and tibble — see
feeds/README.md) and the
environment variable GITHUB_PAT configured with your
GitHub Personal Authentication Token
so that GitHub does not limit your API usage. When generating this PAT, you
should not need to set any scopes (not even "repo"): this process is
read-only, and our work is public.
The files in the _sass and assets directories control the appearance of
this site.
React
Typescript
Django
Laravel
Facebook
Microsoft
Google
Alibaba
D3
Tencent