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

Greg Wilson's avatar
Greg Wilson committed
3
This repository is [Software Carpentry][swc-site] and [Data Carpentry][dc-site]'s
4
template for creating websites for workshops.
5

Greg Wilson's avatar
Greg Wilson committed
6
1.  Please *do not fork this repository directly on GitHub.*
Greg Wilson's avatar
Greg Wilson committed
7
    Instead, please use GitHub's importer following [the instructions below](#creating-a-repository)
8
9
    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
12
    since that is what is
    [automatically published as a website by GitHub][github-project-pages].
13
14

3.  Once you are done,
Raniere Silva's avatar
Raniere Silva committed
15
16
    please fill in [this self-organized workshop form][self-organized-workshop-form]
    and the administrator will contact you if we need any extra information.
Greg Wilson's avatar
Greg Wilson committed
17
18
    We build the list of workshops on our websites from the data included in your `index.html` page.
    We can only do that if you [customize][customization] that page correctly
Raniere Silva's avatar
Raniere Silva committed
19
    *and* [fill in the form][self-organized-workshop-form].
20

Greg Wilson's avatar
Greg Wilson committed
21
22
23
24
25
26
27
28
29
30
If you run into problems,
or have ideas about how to make this process simpler,
please [get in touch](#getting-and-giving-help).
The pages on [customizing your website][customization],
the [FAQ][faq],
and the [design notes][design] have more detail on what we do and why.
And please note:
if you are teaching Git,
please [create a separate repository](#setting-up-a-separate-repository-for-learners)
for your learners to practice in.
31

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

34
35
1.  Log in to GitHub.
    (If you do not have an account, you can quickly create one for free.)
Greg Wilson's avatar
Greg Wilson committed
36
    You must be logged in for the remaining steps to work.
Greg Wilson's avatar
Greg Wilson committed
37

38
2.  Go to [GitHub's importer][importer].
39

Greg Wilson's avatar
Greg Wilson committed
40
41
3.  Paste the url of this repo as the old repository to clone:
    <https://github.com/swcarpentry/workshop-template>.
42
43

4.  Select the owner for your new repository.
44
    (This will probably be you, but may instead be an organization you belong to.)
45

46
5.  Choose a name for your workshop website repository.
47
    This name should have the form `YYYY-MM-DD-site`,
Greg Wilson's avatar
Greg Wilson committed
48
    e.g., `2016-12-01-miskatonic`,
49
    where `YYYY-MM-DD` is the start date of the workshop.
50

51
6.  Make sure the repository is public.
52

53
7.  At this point, you should have a page like this:
54

Greg Wilson's avatar
Greg Wilson committed
55
    ![](fig/using-github-import.png?raw=true)
56

57
58
    You can now click "Begin Import".
    When the process is done,
Greg Wilson's avatar
Greg Wilson committed
59
60
    you will receive a message like
    "Importing complete! Your new repository gvwilson/2016-12-01-miskatonic is ready."
Raniere Silva's avatar
Raniere Silva committed
61
    and you can go to the new repository by clicking on the name.
62

63
64
65
66
67
68
**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).
69

70
## Customizing Your Website
71

72
1.  Go into your newly-created repository,
73
    which will be at `https://github.com/your_username/YYYY-MM-DD-site`.
74
    For example,
Greg Wilson's avatar
Greg Wilson committed
75
    if your username is `gvwilson`,
Greg Wilson's avatar
Greg Wilson committed
76
    the repository's URL will be `https://github.com/gvwilson/2016-12-01-miskatonic`.
77

Greg Wilson's avatar
Greg Wilson committed
78
2.  Edit the header of `index.html` to customize the list of instructors,
79
80
    workshop venue, etc. 
    You can do this in the browser by clicking on it in the file view on GitHub
81
    and then selecting the pencil icon in the menu bar:
Raniere Silva's avatar
Raniere Silva committed
82

Greg Wilson's avatar
Greg Wilson committed
83
    ![](fig/edit-index-file-menu-bar.png?raw=true)
84
    
Andrey Prokopenko's avatar
Andrey Prokopenko committed
85
    Editing hints are embedded in `index.html`,
Greg Wilson's avatar
Greg Wilson committed
86
    and full instructions are in [the customization instructions][customization].
Raniere Silva's avatar
Raniere Silva committed
87

Greg Wilson's avatar
Greg Wilson committed
88
89
90
3.  Alternatively,
    if you are already familiar with Git,
    you can clone the repository to your desktop,
Greg Wilson's avatar
Greg Wilson committed
91
92
    edit `index.html` there,
    and push your changes back to the repository.
93

94
    ~~~
Greg Wilson's avatar
Greg Wilson committed
95
    git clone -b gh-pages https://github.com/your_username/YYYY-MM-DD-site
96
    ~~~
97

Greg Wilson's avatar
Greg Wilson committed
98
    You should specify `-b gh-pages` because the imported repository doesn't have a `master` branch.
99

Greg Wilson's avatar
Greg Wilson committed
100
101
102
103
104
105
106
    In order to view your changes once you are done editing,
    you must push to your GitHub repository:

    ~~~
    git push origin gh-pages
    ~~~

Greg Wilson's avatar
Greg Wilson committed
107
108
    **Note:**
    please do all of your work in your repository's `gh-pages` branch,
Greg Wilson's avatar
Greg Wilson committed
109
    since [GitHub automatically publishes that as a website][github-project-pages].
110

Lex Nederbragt's avatar
Lex Nederbragt committed
111
4.  When you are done editing,
Greg Wilson's avatar
Greg Wilson committed
112
    go to the GitHub Pages URL for your workshop and preview your changes.
Greg Wilson's avatar
Greg Wilson committed
113
    In the example above, this is `https://gvwilson.github.io/2016-12-01-miskatonic`.
114

Lex Nederbragt's avatar
Lex Nederbragt committed
115
116
5.  Optional: you can now change the README.md file in your website's repository, which contains these instructions, so that it contains a short description of your workshop and a link to the workshop website.

Greg Wilson's avatar
Greg Wilson committed
117
118
119
120
**Note:**
this template includes some files and directories that most workshops do not need,
but which provide a standard place to put extra content if desired.
See the [design notes][design] for more information about these.
121

Greg Wilson's avatar
Greg Wilson committed
122
Further instructions are available in [the customization instructions][customization].
Greg Wilson's avatar
Greg Wilson committed
123
124
This [FAQ][faq] includes a few extra tips (additions are always welcome)
and these notes on [the background and design][design] of this template may help as well.
125

Greg Wilson's avatar
Greg Wilson committed
126
## Checking Your Changes
127

Greg Wilson's avatar
Greg Wilson committed
128
129
If you want to preview your changes on your own machine before publishing them on GitHub,
you can do so as described below.
130

Greg Wilson's avatar
Greg Wilson committed
131
132
133
1.  Install the software [described below](#installing-software).
    This may require some work,
    so feel free to preview by pushing to the website.
134

Greg Wilson's avatar
Greg Wilson committed
135
2.  Run the command:
136

Greg Wilson's avatar
Greg Wilson committed
137
    ~~~
Greg Wilson's avatar
Greg Wilson committed
138
    $ jekyll serve
Greg Wilson's avatar
Greg Wilson committed
139
    ~~~
140

Greg Wilson's avatar
Greg Wilson committed
141
142
143
    and go to <http://0.0.0.0:4000> to preview your site.
    You can also run this command by typing `make serve`
    (assuming you have Make installed).
144

Greg Wilson's avatar
Greg Wilson committed
145
146
147
148
149
3.  Run the command `python bin/workshop_check.py index.html`
    to check for a few common errors in your workshop's home page.
    (You must have Python 3 installed to do this.)
    If you have Make installed,
    you can also run this command by typing `make workshop-check`.
150

151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
## (Optional) Linking to Your Page

At the top of your repository on GitHub you'll see

~~~
No description or website provided. — Edit
~~~

Click 'Edit' and add:

1.  A very brief description of your workshop in the "Description" box (e.g., "Miskatonic University workshop, Dec. 2016")

2.  The URL for your workshop in the "Website" box (e.g., `https://gvwilson.github.io/2016-12-01-miskatonic`)

This will help people find your website if they come to your repository's home page.

Greg Wilson's avatar
Greg Wilson committed
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
## Creating Extra Pages

In rare cases,
you may want to add extra pages to your workshop website.
You can do this by putting either Markdown or HTML pages in the website's root directory
and styling them according to the instructions give in
[the lesson template][lesson-example].
If you do this,
you *must* also edit `_config.yml` to set these three values:

1.  `carpentry` is either "dc" (for Data Carpentry) or "swc" (for Software Carpentry).
    This determines which logos are loaded.

2.  `title` is the title of your workshop (typically the venue and date).

3.  `email` is the contact email address for your workshop,
    e.g., `gvwilson@miskatonic.edu`.

Note: `carpentry and `email` duplicate information that's in `index.html`,
but there is no way to avoid this
without requiring people to edit both files in the usual case
where no extra pages are created.

Greg Wilson's avatar
Greg Wilson committed
190
## Installing Software
Raniere Silva's avatar
Raniere Silva committed
191

Greg Wilson's avatar
Greg Wilson committed
192
193
194
195
196
If you want to set up Jekyll
so that you can preview changes on your own machine before pushing them to GitHub,
you must install the software described below.
(Note: Julian Thilo has written instructions for
[installing Jekyll on Windows][jekyll-windows].)
197

Greg Wilson's avatar
Greg Wilson committed
198
199
200
201
202
203
1.  **Ruby**.
    This is included with Linux and Mac OS X;
    the simplest option on Windows is to use [RubyInstaller][ruby-installer].
    You can test your installation by running `ruby --version`.
    For more information,
    see [the Ruby installation guidelines][ruby-install-guide].
204

Greg Wilson's avatar
Greg Wilson committed
205
206
207
2.  **[RubyGems][rubygems]**
    (the package manager for Ruby).
    You can test your installation by running `gem --version`.
208

Greg Wilson's avatar
Greg Wilson committed
209
210
3.  **[Jekyll][jekyll]**.
    You can install this by running `gem install jekyll`.
211

Greg Wilson's avatar
Greg Wilson committed
212
213
214
215
You can check the formatting of your header by running `bin/workshop_check.py`
(which is invoked by `make workshop-check`).
You must have Python 3 installed in order to do this,
and you will also need the [PyYAML][pyyaml] module.
216

217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
## 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
235

236
237
238
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,
Greg Wilson's avatar
Greg Wilson committed
239
240
241
242
243
244
245
246
247
248
249
250
please [file an issue][issues]
or [mail us][contact].

[contact]: mailto:admin@software-carpentry.org
[customization]: https://swcarpentry.github.io/workshop-template/customization/
[dc-site]: http://datacarpentry.org
[design]: https://swcarpentry.github.io/workshop-template/design/
[faq]: https://swcarpentry.github.io/workshop-template/faq/
[github-project-pages]: https://help.github.com/articles/creating-project-pages-manually/
[importer]: http://import.github.com/new
[issues]: https://github.com/swcarpentry/workshop-template/issues
[jekyll-windows]: http://jekyll-windows.juthilo.com/
251
[jekyll]: https://jekyllrb.com/
Greg Wilson's avatar
Greg Wilson committed
252
[lesson-example]: https://swcarpentry.github.io/lesson-example/
Greg Wilson's avatar
Greg Wilson committed
253
254
255
256
[pyyaml]: https://pypi.python.org/pypi/PyYAML
[ruby-install-guide]: https://www.ruby-lang.org/en/downloads/
[ruby-installer]: http://rubyinstaller.org/
[rubygems]: https://rubygems.org/pages/download/
257
[self-organized-workshop-form]: https://amy.software-carpentry.org/workshops/submit/
Greg Wilson's avatar
Greg Wilson committed
258
[swc-site]: http://software-carpentry.org