README.md 9.09 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

Greg Wilson's avatar
Greg Wilson committed
111
112
5.  When you are done editing,
    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

Greg Wilson's avatar
Greg Wilson committed
115
116
117
118
**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.
119

Greg Wilson's avatar
Greg Wilson committed
120
Further instructions are available in [the customization instructions][customization].
Greg Wilson's avatar
Greg Wilson committed
121
122
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.
123

Greg Wilson's avatar
Greg Wilson committed
124
## Checking Your Changes
125

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

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

Greg Wilson's avatar
Greg Wilson committed
133
2.  Run the command:
134

Greg Wilson's avatar
Greg Wilson committed
135
    ~~~
Greg Wilson's avatar
Greg Wilson committed
136
    $ jekyll serve
Greg Wilson's avatar
Greg Wilson committed
137
    ~~~
138

Greg Wilson's avatar
Greg Wilson committed
139
140
141
    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).
142

Greg Wilson's avatar
Greg Wilson committed
143
144
145
146
147
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`.
148

Greg Wilson's avatar
Greg Wilson committed
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
## 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
172
## Installing Software
Raniere Silva's avatar
Raniere Silva committed
173

Greg Wilson's avatar
Greg Wilson committed
174
175
176
177
178
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].)
179

Greg Wilson's avatar
Greg Wilson committed
180
181
182
183
184
185
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].
186

Greg Wilson's avatar
Greg Wilson committed
187
188
189
2.  **[RubyGems][rubygems]**
    (the package manager for Ruby).
    You can test your installation by running `gem --version`.
190

Greg Wilson's avatar
Greg Wilson committed
191
192
3.  **[Jekyll][jekyll]**.
    You can install this by running `gem install jekyll`.
193

Greg Wilson's avatar
Greg Wilson committed
194
195
196
197
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.
198

199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
## 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
217

218
219
220
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
221
222
223
224
225
226
227
228
229
230
231
232
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/
233
[jekyll]: https://jekyllrb.com/
Greg Wilson's avatar
Greg Wilson committed
234
[lesson-example]: https://swcarpentry.github.io/lesson-example/
Greg Wilson's avatar
Greg Wilson committed
235
236
237
238
[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/
239
[self-organized-workshop-form]: https://amy.software-carpentry.org/workshops/submit/
Greg Wilson's avatar
Greg Wilson committed
240
[swc-site]: http://software-carpentry.org