README.md 7.77 KB
Newer Older
1
# workshop-template
Greg Wilson's avatar
Greg Wilson committed
2

3
This repository is [Software Carpentry](http://software-carpentry.org)'s
4
template for creating websites for workshops.
5
6
7
8
9

1.  Do *not* fork this repository directly on GitHub.
    Instead, please follow the instructions below
    to create a website repository for your workshop.

10
2.  Please *do your work in your repository's `gh-pages` branch*,
Greg Wilson's avatar
Greg Wilson committed
11
    since that is what is [automatically published as a website by GitHub](https://help.github.com/articles/creating-project-pages-manually/).
12
13

3.  Once you are done,
14
    please **send your repository's URL to the [Software Carpentry administrator](mailto:admin@software-carpentry.org)**.
15
16
17
18
19
    We build the [list of workshops on the main website](http://software-carpentry.org/workshops/index.html)
    from the data included in your `index.html` page.
    We can only do that if you [customize](CUSTOMIZATION.md) that page correctly
    *and* send us a link to your workshop website.

20
4.  Please also read
21
22
23
24
    [the notes on customizing your website](CUSTOMIZATION.md) and the [FAQ](FAQ.md).
    If you're interested in knowing more about why we do things the way we do,
    please check out the [design notes](DESIGN.md).

25
5.  If you are teaching Git,
26
27
28
    please [create a separate repository](#setting-up-a-separate-repository-for-learners)
    for your learners to practice in.

29
6.  If you run into problems,
30
31
    or have ideas about how to make this process simpler,
    please [get in touch](#getting-and-giving-help).
32

33
## Creating a Repository
Greg Wilson's avatar
Greg Wilson committed
34

35
1.  Go to [GitHub's importer][import].
36

37
2.  Click on "Check the URL".  (GitHub won't import until you've done this.)
38

39
3.  Select the owner for your new repository.
40
    (This will probably be you, but may instead be an organization you belong to.)
41

42
4.  Choose a name for your workshop website repository.
43
44
    This name should have the form `YYYY-MM-DD-site`,
    e.g., `2015-07-01-miskatonic`.
45

46
5.  Make sure the repository is public.
47

48
6.  At this point, you should have a page like this:
49

50
    ![](http://software-carpentry.org/img/workshop-template/using-github-import.png)
51

52
53
54
    You can now click "Begin Import".
    When the process is done,
    you can click "Continue to repository" to visit your newly-created repository.
55

56
57
58
59
60
61
**Note:**
some people have had intermittent errors during the import process,
possibly because of the network timing out.
If you experience a problem, please re-try;
if the problem persists,
please [get in touch](#getting-and-giving-help).
62

63
64
65
66
67
68
69
To clone your new repository, use:

~~~
git clone -b gh-pages https://github.com/your_username/YYYY-MM-DD-site
~~~

This is needed because the imported repository doesn't have a `master` branch.
Pauline Barmby's avatar
Pauline Barmby committed
70

Greg Wilson's avatar
Greg Wilson committed
71
72
**Note:** please do all of your work in your repository's `gh-pages` branch,
since [GitHub automatically publishes that as a website](https://help.github.com/articles/creating-project-pages-manually/).
73

74
## Customizing Your Website
75

76
1.  Go into your newly-created repository,
77
    which will be at `https://github.com/your_username/YYYY-MM-DD-site`.
78
    For example,
Greg Wilson's avatar
Greg Wilson committed
79
    if `your_username` is `gvwilson`,
80
    the repository's URL will be `https://github.com/gvwilson/2015-07-01-mistaktonic`.
81

82
83
84
2.  Edit `index.html` to customize the list of instructors,
    workshop venue,
    etc.
85
86
    You can do this in the browser by clicking on it in the file view
    and then selecting the pencil icon in the menu bar:
Raniere Silva's avatar
Raniere Silva committed
87

88
    ![](http://software-carpentry.org/img/workshop-template/edit-index-file-menu-bar.png)
89

90
91
92
    or you can clone the repository to your desktop,
    edit `index.html` there,
    and push your changes back to the repository.
93

Greg Wilson's avatar
Greg Wilson committed
94
3.  Edit `_config.yml` in the same way
95
    so that `workshop_repo` and `workshop_site`
96
97
98
99
100
101
102
103
    are the URLs of your repository and your GitHub Pages website respectively.

    Note: the URL for your website is determined automatically
    based on the URL for your repository.
    If your repository is at `https://github.com/gvwilson/2015-07-01-mistaktonic`,
    its GitHub Pages website is at `http://gvwilson.github.io/2015-07-01-miskatonic`.

4.  When you are done editing,
Greg Wilson's avatar
Greg Wilson committed
104
    you can preview your website.
105
106
107
    Again,
    if your repository is `https://github.com/your_username/YYYY-MM-DD-site`,
    its website will be `http://your_username.github.io/YYYY-MM-DD-site`.
108

109
110
111
112
113
Editing hints are embedded in `index.html`,
and full instructions are in [CUSTOMIZATION.md](CUSTOMIZATION.md).
This [FAQ](FAQ.md) includes a few extra tips
(additions are always welcome)
and these notes on [the background and design](DESIGN.md) of this template may help as well.
114

115
## Checking Your Changes
116

117
No matter how you edit `index.html`, you should:
118

119
120
1.  Check your changes by running `tools/check.py` at the command line
    from the root directory of your repository.
121

122
2.  Preview your changes by running `tools/preview` and looking at `_site/index.html`.
Greg Wilson's avatar
Greg Wilson committed
123
124
125
    To be able to preview your page locally,
    you must install Ruby 1.9.3 or greater plus `github-pages`,
    as described [below](#installing-software).
126

127
128
For some links to work properly,
particularly the link to your workshop's Eventbrite registration page,
129
130
131
you must view `_site/index.html` using an HTTP server.
If you have Jekyll installed,
you can do this by running:
132

133
134
135
~~~
$ jekyll server -d _site
~~~
136

137
and going to http://localhost:4000.
138

139
140
141
142
## That's it
---------------------------------------------------------
 The following steps are only necesary if you want to run the website locally on your computer.

143
## Installing Software
144
145
146
147
148
149
150
151
152
153
154

In order to preview the workshop website locally on your computer,
you must install the software described below.

> If you aren't able to install this software (or you just can't be
> bothered), you can still create a website for your workshop.  Every
> time you push a change to your website respository the live website
> will update automatically, so you can check your changes on the live
> site instead of locally.

1.  Jekyll 1.0.3
155

Carol Willing's avatar
Carol Willing committed
156
    1. Check if Ruby is installed and find its version using command line:
157
158
159
160
161

        ~~~
        $  ruby -v
        ~~~

162
        The following commands need a minimum version of 1.9.3.
163

164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
    2. Install `github-pages`:

        ~~~
        $ gem install github-pages
        ~~~

        or if that doesn't work:

        ~~~
        $ gem install jekyll
        $ gem install kramdown
        ~~~

        We use Kramdown to translate Markdown into HTML, instead of
        the default Redcarpet, because Kramdown handles Markdown
        inside HTML blocks.

2.  The Python YAML module

    If you are using the Anaconda Python distribution, you probably
    already have it; if you don't, you can install it with:
Raniere Silva's avatar
Raniere Silva committed
185
186

    ~~~
187
    $ conda install pyyaml
Raniere Silva's avatar
Raniere Silva committed
188
    ~~~
189

190
191
    If you are using some other distribution, you can install the
    Python YAML module using Pip:
192

193
194
195
    ~~~
    $ pip install pyyaml
    ~~~
196

197
    and if you are on Debian Linux, you can use:
198

199
200
201
    ~~~
    $ apt-get install python-yaml
    ~~~
202

203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
## Setting Up a Separate Repository for Learners

If you are teaching Git,
you should create a separate repository for learners to use in that lesson.
You should not have them use the workshop website repository because:

*   your workshop website repository contains many files
    that most learners don't need to see during the lesson,
    and

*   you probably don't want to accidentally merge
    a damaging pull request from a novice Git user
    into your workshop's website while you are using it to teach.

You can call this repository whatever you like,
and add whatever content you need to it.

## Getting and Giving Help
221

222
223
224
We are committed to offering a pleasant setup experience for our learners and organizers.
If you find bugs in our instructions,
or would like to suggest improvements,
225
please [file an issue](https://github.com/swcarpentry/workshop-template/issues)
Greg Wilson's avatar
Greg Wilson committed
226
or [mail us](mailto:admin@software-carpentry.org).
227
228

[import]: http://import.github.com/new?import_url=https://github.com/swcarpentry/workshop-template