Software Carpentry Web Site
THIS REPOSITORY IS NO LONGER IN USE.
We have moved our website to https://github.com/swcarpentry/website. Please submit new material there.
This repository holds the source for the old version of the Software Carpentry web site.
Software Carpentry is an open source/open access project, and we welcome contributions of all kinds. By contributing, you are agreeing that Software Carpentry may redistribute your work under these licenses.
Rebuilding the web site locally to check changes requires:
We use Jekyll because it's what GitHub uses; we use Python because most of our volunteers speak it. The Python packages we depend on can be installed using:
$ pip3 install -r requirements.txt
We try to use the same MarkDown interpreters as GitHub does for consistency. On OS X, we suggest you use a recent Ruby to get access to these. If you don't have Homebrew or MacPorts installed, here's a quick recipe to get started using HomeBrew:
ruby -e "$(curl -fsSL https://raw.githubusercontent.com/Homebrew/install/master/install)" brew install ruby gem install jekyll gem install RedCloth
The commands used to rebuild the website are stored in
makeon its own to see a list of all available commands.
make cleanto get rid of generated files.
make cacheto rebuild cached information about workshops and repositories. You only need to do this once a day or so, since that information changes relatively infrequently, but you do need to do it at least once before you can preview the website. (Depending on your machine, this takes 15-30 seconds.)
make siteto build everything in
_sitefor testing. (Depending on your machine, this takes about 10-15 seconds.) You can then open
_site/index.htmland other pages in
_siteto see what your changes will look like.
Note: You must have Jekyll 2.5 or later. If you have an older version installed, you can update it with:
Note: Disqus comments will not load properly, since you'll be on your machine rather than our server.
The simplest way to create a new blog post is to mail the text to Greg Wilson, who will format it and post it for you. If you'd like to submit your post as a pull request, then:
Fork this repository on GitHub, and clone that to your desktop.
Create a file
YYYYis a four-digit year and
MMis a two-digit month. (The directories
YYYY/MMwill already exist unless you're the first person to blog this month or this year.)
Fill in the metadata at the top of the file (or if you have copied an existing blog post, edit the values):
authormust be the author's name. (It does not need to be quoted.)
titleis the post title.
datethe date of the post (in YYYY-MM-DD format).
timemust be an HH:MM clock time, such as 09:30. Every post must have a unique timestamp so that posts can be ordered.
categorymust be a list of category identifiers, e.g.,
["Euphoric State University", "Assessment"]You can use an empty list if you want, and we'll fill in categories for you.
Use HTML to write the post.
<!-- start excerpt -->and
<!-- end excerpt -->to mark a paragraph or two at the start as the excerpt to show in feed readers.
- If you need to refer to our email address, it is
- If you need to refer to another post, or something else on the site, use
Please add any images your blog post needs to the same blog/YYYY/MM directory as the post itself. Please use lower-case names without special characters for image files.
When you're satisfied with your post,
git add path/to/postand
git commit -m "Adding a blog post about something or other"will commit it to your local copy (on your laptop).
git push origin masterwill push it to your clone on GitHub (assuming you've added your fork on GitHub as a remote called
Go to GitHub and issue a pull request from your clone to
swcarpentry/site, then assign it to
Adding a Workshop
Email the workshop's URL to the administrators so that they can add it to our database. The workshop will then show up on the main website the next time it is rebuilt(which typically happens hourly).
For More Advanced Users
make site (and its partners
make dev and
make install) do the following:
bin/preprocess.pyto create the
./_config.ymlfile required by Jekyll and the
_includes/recent_blog_posts.htmlfile containing excerpts of recent blog posts. This tool collects metadata about blog posts and workshops and combines it with static configuration information.
Run Jekyll to build the web site.
bin/make_rss_feed.pyto generate the RSS feed file
bin/make_calendar.pyto generate the ICal calendar file
./_htaccessto create the
.htaccessfile for the web site.
bin/preprocess.py needs two generated files to work properly:
_workshop_cache.yml: stores information about recent and upcoming workshops. This file is created by
_dashboard_cache.yml: stores information about Software Carpentry's GitHub projects. This file is created by
The tool used to rebuild the dashboard cache requires credentials in order to run, since use of GitHub's API is throttled for unauthenticated users and programs. If you wish to regenerate these files:
Get a GitHub API token.
Save it in a file called
git-token.txtin the root directory of this site. (This file is ignored by Git, since tokens should not be shared between people.)
you can run
make cache to re-create the two files.
Please do not commit them.
$ pip3 install pypng
bin/badge-create.py to create a new badge, e.g.:
$ python3 bin/badge-create.py username email instructor
To bake the badge we use
bin/badgebakery.py which was provided by the Open Badge Team.