There are a few things you need to know in order to understand why we do things the way we do. Some of them are specific to GitHub, rather than Git itself.
-
Git uses the term "clone" to mean "a copy of a repository". GitHub uses the term "fork" to mean, "a copy of a GitHub-hosted repo that is also hosted on GitHub", and the term "clone" to mean "a copy of a GitHub-hosted repo that's located on someone else's machine". In both cases, the duplicate has a remote called
origin
that points to the original repo; other remotes can be added manually. -
A user on GitHub can only have one fork of a particular repo. This is a problem for us because an instructor may be involved in several workshops, each of which has its own website repo. Those website repositories ought to be forks of this one, but since GitHub doesn't allow that, we have to use
import.github.com
as described in the main page. -
If a repository has a file called
README.md
in its root directory, GitHub displays the contents of that file on the repository's home page. -
If a repository has a branch called
gh-pages
(which stands for "GitHub pages"), then GitHub uses the HTML and Markdown files in that branch to create a website for the repository. If the repository's URL ishttp://github.com/darwin/finches
, the URL for the website ishttp://darwin.github.io/finches
. -
If an HTML or Markdown file has a header consisting of three dashes, some data about the page, and three more dashes:
--- key: value other_key: other_value --- stuff in the page
then GitHub doesn't just copy the file over verbatim. Instead, it runs the file through a translator called Jekyll that looks for specially-formatted commands embedded in the file and uses them to fill in the page.
-
Commands can be embedded in the body of a page. One is
{% raw %}{% include something.html %}{% endraw %}
, which tells Jekyll to copy the contents ofsomething.html
into the file being translated; this is used to create standard headers and footers for pages. Another is{{variable}}
: when Jekyll sees this, it replaces it with the value ofvariable
. This is used to insert things like a contact email address and the URL for our Twitter account. -
Jekyll gets variables from two places: a file called
_config.yml
located in the repo's root directory, and the header of each individual page. Variables from_config.yml
are put in an object calledsite
, and referred to assite.variable
, so that (for example){{site.swc_site}}
in a page is replaced by the URL of the main Software Carpentry web site. Variables from the page's header are put in an object calledpage
, and referred to aspage.variable
, so if a page's header defines a variable calledvenue
,{{page.venue}}
is replaced by "Euphoric State University" (or whatever value the variable has). -
If a page uses
{% raw %}{% include something.html %}{% endraw %}
to include a snippet of HTML, Jekyll looks in a directory called_includes
to findsomething.html
. It always looks there, and nowhere else, so anything we want people to be able to include in their pages has to be stored in_includes
. -
A repository can have another special directory called
_layouts
. If a page likeindex.html
has a variable calledlayout
, and that variable's value isstandard.html
, Jekyll loads the file_layouts/standard.html
and copies the content ofindex.html
into it, then expands the result. This is used to give the pages in a site a uniform appearance. We have created two layouts for workshop pages:-
workshop.html
is used for workshops' home pages, and is the layout for theindex.html
page in your repo's root directory. Thatindex.html
page's header must define several variables as specified in CUSTOMIZATION.md in order for your workshop to be included in our main website. -
page.html
is used for any other pages you want to create.
-