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

3
4
5
6
7
This repository is [Software Carpentry](http://software-carpentry.org)'s
template for creating websites for workshops.  Do *not* fork this
repository directly on GitHub.  Instead, follow the instructions below
to create a website repository for your workshop (and possibly a
second repository for your learners to use in your Git lessons).
8

9
10
11
12
13
14
15
16
17
18
19
20
> 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.

## Semi-Automated Setup
21
22

1.  Download the workshop website creation script from
23
    [http://files.software-carpentry.org/swc-workshop-create](http://files.software-carpentry.org/swc-workshop-create).
Greg Wilson's avatar
Greg Wilson committed
24

25
2.  Make sure that you are *not* inside another Git repository.
26

27
28
3.  Run the workshop website creation script with no parameters - it
    will print a help message telling you what parameters it needs.
29

Raniere Silva's avatar
Raniere Silva committed
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
    You need to use

    ~~~
    $ bash swc-workshop-create
    ~~~

    or change file mode with

    ~~~
    $ chmod +x swc-workshop-create
    ~~~

    before run the script by

    ~~~
    $ ./swc-workshop-create
    ~~~

48
4.  Run the script with those parameters.
49

50
5.  Go into your newly-created repository.
51

52
53
6.  Edit `index.html`.  Hints are embedded in the file, and full
    instructions are in [CUSTOMIZATION.md](CUSTOMIZATION.md).
54

55
7.  If you have installed the software described below:
56

57
58
    1.  Check your changes by running `tools/check.py` inside your
        repository.
59

60
61
    2.  Preview your changes by running `tools/preview` and looking at
        `_site/index.html`.
62

63
64
65
66
67
68
69
70
71
72
    3.  For some links work properly, **including the one to Eventbrite**, you
        will need to look at `_site/index.html` provide by a HTTP server that
        can be done using

        ~~~
        $ jekyll server -d _site
        ~~~

        and look at http://localhost:4000.

73
74
75
76
8.  Commit your changes and push to the `gh-pages` branch of your
    repository.

9.  Send the workshop coordinators the URL for your GitHub repository.
77
78
79
80

If the identifier for your workshop is `2015-07-01-esu`, and your
GitHub username is `ghopper`, your workshop repository will be
`https://github.com/ghopper/2015-07-01-esu` and the website for your
81
82
workshop will be `https://ghopper.github.io/2015-07-01-esu`.  (Note:
the workshop coordinators will want the former URL, not the latter.)
83

84
## Manual Setup
85

86
You can set up your repository manually instead of using the automated
87
88
`create` script.  As above, we will assume that your user ID is
`ghopper` and the identifier for your workshop is `2015-07-01-esu`.
89

90
1.  Create an empty repository on GitHub called `2015-07-01-esu`.
91

Greg Wilson's avatar
Greg Wilson committed
92
93
2.  Clone the template repository to your computer in a directory with
    the same name as your workshop identifier:
Raniere Silva's avatar
Raniere Silva committed
94
95

    ~~~
Matt Davis's avatar
Matt Davis committed
96
    $ git clone -b gh-pages -o upstream https://github.com/swcarpentry/workshop-template.git 2015-07-01-esu
Raniere Silva's avatar
Raniere Silva committed
97
98
99
100
101
102
103
    ~~~

3.  Go into that directory using

    ~~~
    $ cd 2015-07-01-esu
    ~~~
104

Matt Davis's avatar
Matt Davis committed
105
4.  Add your GitHub repository as a remote called `origin` using
Raniere Silva's avatar
Raniere Silva committed
106
107

    ~~~
Matt Davis's avatar
Matt Davis committed
108
    $ git remote add origin https://github.com/ghopper/2015-07-01-esu.git
Raniere Silva's avatar
Raniere Silva committed
109
    ~~~
110

111
112
5.  Edit `index.html`.  Hints are embedded in the file, and full
    instructions are in [CUSTOMIZATION.md](CUSTOMIZATION.md).
113

114
6.  If you have installed the software described below:
Raniere Silva's avatar
Raniere Silva committed
115

116
117
118
119
120
121
    1.  Check your changes by running `tools/check.py` inside your
        repository.

    2.  Preview your changes by running `tools/preview` and looking at
        `_site/index.html`.

122
123
124
125
126
127
128
129
130
131
    3.  For some links work properly **including the one to Eventbrite** you
        will need to look at `_site/index.html` provide by a HTTP server that
        can be done using

        ~~~
        $ jekyll server -d _site
        ~~~

        and look at http://localhost:4000.

132
7.  Commit your changes and push to the `gh-pages` branch of your
133
134
135
136
137
    repository using

    ~~~
    $ git push origin gh-pages
    ~~~
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158

8.  Manually add the other instructors as collaborators to your Github
    repository.

9.  Send the workshop coordinators the URL for your GitHub repository.

Note that SSH cloning (as opposed to the HTTPS cloning used above)
will also work for those who have set up SSH keys with GitHub.

## Previewing Changes Locally

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
159

Carol Willing's avatar
Carol Willing committed
160
    1. Check if Ruby is installed and find its version using command line:
161
162
163
164
165

        ~~~
        $  ruby -v
        ~~~

166
        The following commands need a minimum version of 1.9.3.
167

168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
    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
189
190

    ~~~
191
    $ conda install pyyaml
Raniere Silva's avatar
Raniere Silva committed
192
    ~~~
193

194
195
    If you are using some other distribution, you can install the
    Python YAML module using Pip:
196

197
198
199
    ~~~
    $ pip install pyyaml
    ~~~
200

201
    and if you are on Debian Linux, you can use:
202

203
204
205
    ~~~
    $ apt-get install python-yaml
    ~~~
206

207
## Final Steps
208

209
210
211
212
213
The final step in creating a website for your workshop is to customize
its home page by following [these instructions](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.
214

215
## Getting Help
216

217
218
219
Mail us at [admin@software-carpentry.org](mailto:admin@software-carpentry.org),
or join our [discussion list](http://lists.software-carpentry.org/mailman/listinfo/discuss_lists.software-carpentry.org)
and ask for help there.
220

Greg Wilson's avatar
Greg Wilson committed
221
## Giving Help
Carol Willing's avatar
Carol Willing committed
222

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