This is the repository for the new Carpentries website. Please submit additions and fixes as pull requests to our GitHub repository.
Lessons are not stored in this repository: please see the Software Carpentry lessons page or the Data Carpentry lessons page for links to the many individual lesson repositories.
The Carpentries (Software and Data 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.
You will also need Python 3 with PyYAML available in order to re-generate the data files the site depends on.
Please do not use jekyll build
or jekyll serve
directly to build or view the website.
Instead, you should use the following commands:
make
ormake 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 clean
removes the_site
directory and any Emacs editor backup files littering the source directories.
The details describes a few more advanced commands as well. Please note that rebuilding this site can take 3-4 minutes on a moderately powerful laptop, and occasionally times out on GitHub. We're working on it...
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 http://software-carpentry.org/blog/YYYY/MM/some-title.html
.
The YAML header of a blog post must look like this:
---
layout: post
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 our database.
Do not edit the YAML in _data/amy.yml
:
this is overwritten every time the website is rebuilt on the server.
This website depends on three data files,
each of which is rebuilt by make
:
-
make amy
regenerates_data/amy.yml
, which contains information about upcoming workshops, instructors' locations, and so on that is fetched from our online workshop management tool. You must be logged in to AMY in order to run this. -
make dashboard
generates_data/dashboard.yml
, which contains information about the state of our GitHub repositories. In order to run this, you must get a GitHub API token and store it in$HOME/.git-token
. -
make includes
to rebuild the data file_data/includes.yml
. This does not require special permissions, but is only necessary if you have added more people to_includes/people
or more projects to_includes/projects
. (We plan to move the content of these two directories to_data
so thatmake includes
will no longer be needed.)
We cache the output of these commands in the _data
directory
so that people can rebuild the site without needing special permissions.
The files in the _sass
and 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.
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 software-carpentry.org ./rebuild-site.sh