How to use/edit this site
This is a static website automatically generated with Jekyll by GitHub Pages. The source code is available on GitHub and you are free to copy it, modify it and share it under the terms of the Creative Commons 4.0 BY-SA license.
You are a student, a collaborator, or a casual visitor to this site and want to learn how to take advantage of the freedom offered to you by the CC license, this help page is for you!
Quickly editing pages for collaborators
This will drop you in GitHub’s file editing interface, where you can modify the source code, preview it, and commit your changes by giving a short description of what you modified.
CAVEATS: The Markdown engine used by this site is Kramdown. Its syntax definitions are slightly different form GitHub Flavored Markdown, thus the preview feature in GitHub might not render source as in the final result.
Other reasons why GitHub’s preview may not correspond to the final results are:
- Use of Liquid templates in the source. This is seldom used, but some pages (like this one) use them to access site-wide configuration variables.
- Use of special purpose markup, HTML, and scripts, such as mathematical excerpts written in MathJax.
Copying the site for your own use
You want to get a copy of the website and its source code to analyze it, or because you are afraid that I might take it down someday, this is very easily done, even if you’re not (yet!) the technical type.
Now you can make changes to your own copy of the site. Edit some files, commit the changes, and examine the result. The compiled static site will be served at http://username.github.io/in202 (replace username by your GitHub user name).
Note: the website will not be compiled when you first fork the repository. If you want your fork to be served on github.io before committing any changes, you will have to create a local clone of your fork, then push. This will not create any new commit, but will force GitHub to compile your copy of the site. In a Unix shell, this is
git clone firstname.lastname@example.org:username/in202.git cd in202 git push
Contributing your changes back to this site
You have forked the repository, made your changes, and now want to contribute them back to the site, but you do not have write access.
Pull requests are GitHub’s standard way of contributing changes back to the original repository. You can make a pull request for this repository, and I will be happy to review your changes and integrate them.
You want to do more than the occasional typo fix, or you want to deeply modify the code to make your own site. GitHub’s editor and preview are too limited for this, and handling git history via GitHub’s web interface becomes too clumsy at this point. You need to work locally on your computer.
At some point, you will need to preview your work, but pushing to GitHub each time you want to preview is clumsy. Your best option is to install Jekyll and the required dependencies on your machine. It is recommended to install the GitHub pages gem which provides you with the exact same versions used by GitHub to compile your site.
If you already have Ruby
>1.9.3, the install part should be as easy as
gem install github-pages
Note that you will need Ruby headers (
ruby-dev package on Ubuntu) in
order to compile C dependencies.
Now you can
cd into your local clone of the repository and launch
the compilation by
jekyll serve -w -b''
Your site will be generated in a
_site sub-directory, and served
live at http://localhost:4000/. Any changes to the sources will
trigger an automatic recompilation!
Have fun coding!
Note: you will notice that the source for the site is in a branch
gh-pages. If you are familiar with Git, this
will surprise you as the usual branch name for Git repositories is
master. This special name is where all the GitHub pages magic comes
from: name your branch
gh-pages, and GitHub will automatically
compile it when you push.
Using the template
You can start from there to create your own site. Beware that some of the features of this site may be experimental and not integrated in the template.