The Carpentries Website
Lessons are not stored in this repository: please see the Software Carpentry lessons page, the Data Carpentry lessons page, or the Library Carpentry lessons page for links to the many individual lesson repositories.
The Carpentries (Software, Data, and Library Carpentry) are open projects, 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.0.0 or higher of Ruby and the package manager Bundler. (The package manager is used to make sure you use exactly the same versions of software as GitHub Pages.) After checking out the repository, please run:
$ bundle install
to install Jekyll and the software it depends on. 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:
make commands: list available commands.
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
(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.
your blog post will appear as
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"] ---
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.
layout: page-fullwidth permalink: /some/path/ title: Title in Title Case
You must then also add the page to
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 our database.
Do not edit the YAML in
this is overwritten every time the website is rebuilt on the server.
How is the site built and rendered?
The website is served directly by GitHub pages. Each time a commit is pushed to the repository and every 24 hours, Travis does 3 things:
- it retrieves the latest version of the data feeds needed by the website (see below),
and pushes them to the
_datafolder (only for commits to the
gh-pagesbranch, not for pull requests)
- it validates the YAML headers of all the pages and blog posts
- it builds the website
Steps 2 and 3 allow us to detect possible issues with formatting that would prevent the website to render properly.
The data files for the workshops and the instructors are generated every 6 hours from AMY (via our redash server) by the script in the amy-feeds repository. These files are served at https://feeds.carpentries.org/.
During the Travis process, these files are being pulled from their source and pushed to this website repository.
The files in the
assets directories control the appearance of this site.
Their contents are pulled in manually from a stand-alone https://github.com/swcarpentry/styles repository,
which also controls the appearance of
the workshop template
and lesson template.
Please contact us before modifying any of these files
so that we can figure out the best way to incorporate your improvements.
Rebuilding the Main Web Site
A copy of the shell script
bin/rebuild-site.sh is installed in the website's home directory on our server
and re-run hourly by cron.
If you are able to ssh to the server,
it can be re-run manually as:
$ ssh carpentries.org ./rebuild-site.sh