Commit 5843bc4d authored by Greg Wilson's avatar Greg Wilson
Browse files

Merge pull request #138 from gvwilson/explaining-setup-using-github-import

Updating setup instructions to reflect use of GitHub Import.
parents 53bcd731 48c5eda1
# Customizing Your Workshop's Website
You must change the values of `lesson_repo` and `lesson_site` in
the `_config.yml` configuration file in the root directory of your
workshop to point to the repository for the lesson and its GitHub
pages URL respectively. You should not need to modify any of the
other values in `_config.yml`.
## Configuration File
Your workshop's `index.html` page must define the following values
in its header:
You must edit the `_config.yml` configuration file in the root directory of your workshop
and change the URLS called `lesson_repo` and `lesson_site`
to point to the repository for the lesson and its GitHub Pages site respectively.
If the URL for the repository is `https://github.com/gvwilson/2015-07-01-mistaktonic`,
the URL for the website will be `http://gvwilson.github.io/2015-07-01-miskatonic`.
You should not need to modify any of the other values in `_config.yml`.
## Home Page: Data
Your workshop's home page lives in `index.html`,
which must define the following values in its header:
* `layout` must be `workshop`.
......@@ -72,11 +78,18 @@ in its header:
The header may optionally define the following:
* `eventbrite` is the multi-digit Eventbrite registration key. If you
are using Eventbrite, the admins will set this key for you. If
you are using something else for registration, it may be deleted.
Note: this value must be given as a string in double quotes, rather
than as a number.
* `etherpad` is the URL for the Etherpad for your workshop. If you are
not using an Etherpad, you can delete this value.
not using an Etherpad, you can delete this line.
* `eventbrite` is the multi-digit Eventbrite registration key. If you
are using Eventbrite, the Software Carpentry administraotrs will
give this to you. If you are using something else, you may delete
this line. Note: this value must be given as a string in double
quotes, rather than as a number.
## Home Page: Schedule, Syllabus, and Setup
You should edit the sections titled `Schedule` and `Syllabus`
so that they show what you're actually planning to teach and when.
You should also delete irrelevant parts of the section titled `Setup`
so that your learners don't try to install software that they won't need.
......@@ -16,11 +16,12 @@ than Git itself.
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've had to find a workaround.
GitHub doesn't allow that, we have to use `import.github.com`
as described in [the main page](README.md#creating-a-repository).
3. If a repository has a file called `README.md` in its root
directory, GitHub displays that file on the repository's home
page.
directory, GitHub displays the contents of that file on the
repository's home page.
4. If a repository has a branch called `gh-pages` (which stands for
"GitHub pages"), then GitHub uses the HTML and Markdown files in
......@@ -46,7 +47,7 @@ than Git itself.
them to fill in the page.
6. Commands can be embedded in the body of a page. One is
{% raw %}{% include something.html %}{% endraw %}, which tells
`{% raw %}{% include something.html %}{% endraw %}`, which tells
Jekyll to copy the contents of `something.html` into the file
being translated; this is used to create standard headers and
footers for pages. Another is `{{variable}}`: when Jekyll sees
......@@ -65,7 +66,7 @@ than Git itself.
called `venue`, `{{page.venue}}` is replaced by "Euphoric State
University" (or whatever value the variable has).
8. If a page uses {% raw %}{% include something.html %}{% endraw %}
8. If a page uses `{% raw %}{% include something.html %}{% endraw %}`
to include a snippet of HTML, Jekyll looks in a directory called
`_includes` to find `something.html`. It always looks there, and
nowhere else, so anything we want people to be able to include in
......
## FAQ
# FAQ
* *Where can I get help?*
......@@ -11,37 +11,40 @@
Please file an issue against [https://github.com/swcarpentry/workshop-template](this repository)
or [mail us](mailto:admin@software-carpentry.org).
* *Why does the workshop repository have to be created from scratch? Why not fork `workshop-template` on GitHub?*
* *Why does the workshop repository have to be created using `import.github.com`? Why not fork `workshop-template` on GitHub?*
Because any particular user can only have one fork of a repository,
but instructors frequently need to work on several workshops at once.
* *Why use Jekyll? Why not some other markup language and some other converter?*
Because it's the default on GitHub. If we're going to teach
people to use that site, we should teach them to use it as it is,
Because it's the default on GitHub.
If we're going to teach people to use that site,
we should teach them to use it as it is,
not as we wish it was.
* *Where should pages go if multiple workshops are running at a site simultaneously?*
Use subdirectories like `2015-07-01-esu/beginners`, so that main
directory names always follow our four-part convention.
Use subdirectories like `2015-07-01-esu/beginners`,
so that main directory names always follow our four-part convention.
* *What if I want to add more values to the page, like `address1` and `address2` for different rooms on different days?*
* *What if I want to add more values to `index.html`, like `address1` and `address2` for different rooms on different days?*
Go ahead, but you *must* have the variables described in
[CUSTOMIZATION.md](CUSTOMIZATION.md).
Go ahead,
but you *must* have the variables described in [CUSTOMIZATION.md](CUSTOMIZATION.md).
Please make sure to run `tools/check.py` after adding or changing variables
to make sure that our main website will understand your changes.
* *What is the "Windows installer"?*
We have built a small installation helper for Windows that
installs `nano` and `sqlite`, adds R to the path, and so on. It
is maintained in
We have built a small installation helper for Windows
that installs `nano` and `sqlite`, adds R to the path, and so on.
It is maintained in
[https://github.com/swcarpentry/windows-installer](https://github.com/swcarpentry/windows-installer),
which also has an up-to-date description of what it actually does.
The latest version is always available at
[http://files.software-carpentry.org/SWCarpentryInstaller.exe](http://files.software-carpentry.org/SWCarpentryInstaller.exe),
and contributions are always welcome.
[http://files.software-carpentry.org/SWCarpentryInstaller.exe](http://files.software-carpentry.org/SWCarpentryInstaller.exe);
contributions are always welcome.
* *What do the [labels](https://github.com/swcarpentry/lesson-template/issues?q=is%3Aopen+is%3Aissue) mean?*
......@@ -49,7 +52,8 @@
* `discussion`: marks issues used for conversations about specific problems and questions
* `duplicate`: marks an issue that was closed as redundant (include the number of the original issue in the closing comment)
* `enhancement`: asks for, or adds, a new feature or new information
* `filed-by-newcomer`: issue or pull request was filed by someone who is relatively new to GitHub and/or this project, and would appreciate guidance as well as feedback
* `filed-by-newcomer`: issue or pull request was filed by someone who is relatively new to GitHub and/or this project,
and would appreciate guidance as well as feedback
* `help-wanted`: a question or request for assistance
* `leave-as-is`: marks an issue closed because the item in question will be left as is
* `suitable-for-newcomer`: issue or pull request is a good starting point for someone who is relatively new to GitHub and/or this project
......@@ -57,7 +61,7 @@
## Debugging
* *Eventbrite registration isn't show at workshop's home page.*
* *Eventbrite registration isn't showing up on the workshop's home page.*
First check that you have something like
......@@ -65,19 +69,23 @@
eventbrite: 1234567890AB
~~~
at the YAML header of `index.html`. If the YAML header is set properly you
probably are accessing
file:///home/to/workshop/directory/_site/index.html. Please run
at the YAML header of `index.html`.
If the YAML header is set properly you probably are accessing
`file:///home/to/workshop/directory/_site/index.html` directly.
Instead,
please run
~~~
$ jekyll server -d _site
~~~
and look at http://localhost:4000.
and look at `http://localhost:4000` in your browser
(or push your changes to GitHub and view your page there).
* *What do I do if I see a `invalid byte sequence in ...` error when I run `tools/check`?*
Declare the `en_US.UTF-8` locale in your shell:
Your computer is telling you that it doesn't understand some of the characters you're using.
Declare your locale to be `en_US.UTF-8` in your shell:
~~~
$ export LC_ALL=en_US.UTF-8
......@@ -98,9 +106,11 @@
done.
~~~
This is a [problem in Pygments.rb](http://stackoverflow.com/questions/17364028/jekyll-on-windows-pygments-not-working).
Uninstall pygments.rb 0.5.1 or 0.5.2, install 0.5.0. For example, here's how you would
uninstall pygments 0.5.2 and restore version 0.5.0:
This is a [problem in Pygments.rb](http://stackoverflow.com/questions/17364028/jekyll-on-windows-pygments-not-working),
which Jekyll uses for syntax highlighting.
To fix the problem
uninstall pygments.rb 0.5.1 or 0.5.2 and install version 0.5.0.
For example, here's how you would uninstall pygments 0.5.2 and restore version 0.5.0:
~~~
$ gem uninstall pygments.rb --version "=0.5.2"
......@@ -135,8 +145,9 @@
~~~
This installs Jekyll in `/usr/local/bin`,
so make sure this directory comes before `/usr/bin` in your `PATH` environment variable,
so that:
so make sure this directory comes before `/usr/bin` in your `PATH` environment variable.
When your path is set correctly,
you should see:
~~~
$ which jekyll
......@@ -153,17 +164,15 @@
For more information, see
[http://michaelchelen.net/81fa/install-jekyll-2-ubuntu-14-04/](this article).
* *Help, my website isn't rendering correctly once its pushed to GitHub!*
This can occur if you're trying to view the website over a
HTTPS connection because the content from the Software
Carpentry website is not currently served over HTTPS. Your
browser sees this as unsecure content, so won't load it.
To solve this simply load the website over HTTP, and make
sure the link you distribute uses http:// instead of https://.
If you're using a browser plugin like HTTPS everywhere, you
will need to disable it for your workshop's site.
This can occur if you're trying to view the website over a HTTPS connection
because the content from the Software Carpentry website is not currently served over HTTPS.
Your browser sees this as unsecure content, so won't load it.
To solve this,
use `http` in the URL instead of `https`
and make sure the link you distribute does so as well.
If you're using a browser plugin like [HTTPS Everywhere](https://www.eff.org/https-everywhere)
you will need to disable it for your workshop's site.
We are presently (January 2015) working to get HTTPS working properly on our website.
# workshop-template
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).
template for creating websites for workshops.
> 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.
1. Do *not* fork this repository directly on GitHub.
Instead, please follow the instructions below
to create a website repository for your workshop.
## Semi-Automated Setup
2. Once you are done,
please **send your repository's URL to the Software Carpentry administrator**.
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.
1. Download the workshop website creation script from
[http://files.software-carpentry.org/swc-workshop-create](http://files.software-carpentry.org/swc-workshop-create).
3. Please also read
[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).
2. Make sure that you are *not* inside another Git repository.
4. If you are teaching Git,
please [create a separate repository](#setting-up-a-separate-repository-for-learners)
for your learners to practice in.
3. Run the workshop website creation script with no parameters - it
will print a help message telling you what parameters it needs.
5. If you run into problems,
or have ideas about how to make this process simpler,
please [get in touch](#getting-and-giving-help).
You need to use
## Creating a Repository
~~~
$ bash swc-workshop-create
~~~
or change file mode with
~~~
$ chmod +x swc-workshop-create
~~~
before run the script by
~~~
$ ./swc-workshop-create
~~~
1. Go to [http://import.github.com](http://import.github.com).
4. Run the script with those parameters.
2. Enter the URL for this template repository, which is
`https://github.com/swcarpentry/workshop-template`.
5. Go into your newly-created repository.
3. Check the URL. (GitHub won't import until you've done this.)
6. Edit `index.html`. Hints are embedded in the file, and full
instructions are in [CUSTOMIZATION.md](CUSTOMIZATION.md).
4. Select the owner for your new repository.
(This will probably be you, but may instead be an organization you belong to.)
7. If you have installed the software described below:
5. Choose a name for your workshop website repository.
This name should have the form `YYYY-MM-DD-site`,
e.g., `2015-07-01-miskatonic`.
1. Check your changes by running `tools/check.py` inside your
repository.
6. Make sure the repository is public.
2. Preview your changes by running `tools/preview` and looking at
`_site/index.html`.
7. At this point, you should have a page like this:
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
![](http://software-carpentry.org/img/workshop-template/using-github-import.png)
~~~
$ jekyll server -d _site
~~~
You can now click "Begin Import".
When the process is done,
you can click "Continue to repository" to visit your newly-created repository.
and look at http://localhost:4000.
**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).
8. Commit your changes and push to the `gh-pages` branch of your
repository.
## Customizing Your Website
9. Send the workshop coordinators the URL for your GitHub repository.
1. Go into your newly-created repository,
which will be at `https://github.com/your_username/YYYY-MM-DD-site`.
For example,
if `your_username` is `gvwilson`,
the repository's URL will be `https://github.com/gvwilson/2015-07-01-mistaktonic`.
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
workshop will be `https://ghopper.github.io/2015-07-01-esu`. (Note:
the workshop coordinators will want the former URL, not the latter.)
2. Edit `index.html` to customize the list of instructors,
workshop venue,
etc.
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:
## Manual Setup
![](http://software-carpentry.org/img/workshop-template/edit-index-file-menu-bar.png)
You can set up your repository manually instead of using the automated
`create` script. As above, we will assume that your user ID is
`ghopper` and the identifier for your workshop is `2015-07-01-esu`.
or you can clone the repository to your desktop,
edit `index.html` there,
and push your changes back to the repository.
To be able to preview your page locally, you'll need `ruby` 1.9.3 or greater,
plus `github-pages` installed, as described [below](#previewing-changes-locally).
3. Edit `_config.yml` in the same way
so that `lesson_repo` and `lesson_site`
are the URLs of your repository and your GitHub Pages website respectively.
1. Create an empty repository on GitHub called `2015-07-01-esu`.
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`.
2. Clone the template repository to your computer in a directory with
the same name as your workshop identifier:
4. When you are done editing,
you can preview your website.
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`.
~~~
$ git clone -b gh-pages -o upstream https://github.com/swcarpentry/workshop-template.git 2015-07-01-esu
~~~
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.
3. Go into that directory using
## Checking Your Changes
~~~
$ cd 2015-07-01-esu
~~~
No matter how you edit `index.html`, you should:
4. Add your GitHub repository as a remote called `origin` using
1. Check your changes by running `tools/check.py` at the command line
from the root directory of your repository.
~~~
$ git remote add origin https://github.com/ghopper/2015-07-01-esu.git
~~~
2. Preview your changes by running `tools/preview` and looking at `_site/index.html`.
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).
5. Edit `index.html`. Hints are embedded in the file, and full
instructions are in [CUSTOMIZATION.md](CUSTOMIZATION.md).
For some links to work properly,
particularly the link to your workshop's Eventbrite registration page,
you must view `_site/index.html` using an HTTP server.
If you have Jekyll installed,
you can do this by running:
6. If you have installed the software described [below](#preview-changes):
~~~
$ jekyll server -d _site
~~~
1. Check your changes by running `tools/check.py` inside your
repository.
and going to http://localhost:4000.
2. Preview your changes by running `tools/preview` and looking at
`_site/index.html`.
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.
7. Commit your changes and push to the `gh-pages` branch of your
repository using
~~~
$ git push origin gh-pages
~~~
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
## Installing Software
In order to preview the workshop website locally on your computer,
you must install the software described below.
......@@ -207,24 +185,31 @@ you must install the software described below.
$ apt-get install python-yaml
~~~
## Final Steps
## Setting Up a Separate Repository for Learners
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.
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:
## Getting Help
* 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
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.
## Giving Help
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, please
[file an issue](https://github.com/swcarpentry/workshop-template/issues?q=is%3Aopen+is%3Aissue)
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,
please [file an issue](https://github.com/swcarpentry/workshop-template/issues)
or [mail us](mailto:admin@software-carpentry.org).
<span id="github-ribbon"><a href="https://github.com/swcarpentry/bc">Fork me on GitHub</a></span>
<div class="banner">
<a href="http://software-carpentry.org" title="Software Carpentry">
<img alt="Software Carpentry banner" src="{{site.swc_site}}/v5/img/software-carpentry-banner.png" />
<img alt="Software Carpentry banner" src="{{site.swc_site}}/img/software-carpentry-banner.png" />
</a>
</div>
<link rel="shortcut icon" type="image/x-icon" href="{{site.swc_site}}/favicon.ico" />
<link href="{{site.swc_site}}/v5/css/bootstrap/bootstrap.css" rel="stylesheet" />
<link href="{{site.swc_site}}/css/bootstrap/bootstrap.css" rel="stylesheet" />
<meta name="viewport" content="width=device-width, initial-scale=1.0" />
<link href="{{site.swc_site}}/v5/css/bootstrap/bootstrap-responsive.css" rel="stylesheet" />
<link href="{{site.swc_site}}/css/bootstrap/bootstrap-responsive.css" rel="stylesheet" />
<link rel="stylesheet" type="text/css" href="{{site.swc_site}}/v5/css/swc.css" />
<link rel="stylesheet" type="text/css" href="{{site.swc_site}}/v5/css/swc-bootstrap.css" />
<link rel="alternate" type="application/rss+xml" title="The Software Carpentry Blog" href="{{config.site}}/feed.xml"/>
......
<!-- Javascript placed at the end of the document so the pages load faster. -->
<script src="{{site.swc_site}}/v5/js/jquery-1.9.1.min.js"></script>
<script src="{{site.swc_site}}/v5/js/bootstrap/bootstrap.min.js"></script>
<script src="{{site.swc_site}}/js/jquery-1.9.1.min.js"></script>
<script src="{{site.swc_site}}/js/bootstrap/bootstrap.min.js"></script>
......@@ -17,12 +17,16 @@ etherpad: # FIXME (insert the URL for your Etherpad if you're using one)
eventbrite: # FIXME (delete this if not used, otherwise uncomment and provide 1234567890AB key for Eventbrite registration)
---
<!--
HEADER
Edit the values in the block above to be appropriate for your
workshop. Run 'tools/check' *before* committing to make sure that
changes are good.
-->
<!--
EVENTBRITE
This block includes the Eventbrite registration widget if
'eventbrite' has been set in the header. You can delete it if you
are not using Eventbrite, or leave it in, since it will not be
......@@ -41,6 +45,8 @@ eventbrite: # FIXME (delete this if not used, otherwise uncomment and provide 12
<h2>General Information</h2>
<!--
INTRODUCTION
Edit the general explanatory paragraph below if you want to change
the pitch.
-->
......@@ -56,6 +62,8 @@ eventbrite: # FIXME (delete this if not used, otherwise uncomment and provide 12
</p>
<!--
AUDIENCE
Explain who your audience is. (In particular, tell readers if the
workshop is only open to people from a particular institution.
-->
......@@ -65,6 +73,8 @@ eventbrite: # FIXME (delete this if not used, otherwise uncomment and provide 12
</p>
<!--
LOCATION
This block displays the address and links to maps showing directions
if the latitude and longitude of the workshop have been set. You
can use http://itouchmap.com/latlong.html to find the lat/long of an
......@@ -82,6 +92,8 @@ eventbrite: # FIXME (delete this if not used, otherwise uncomment and provide 12
{% endif %}
<!--
SPECIAL REQUIREMENTS
Modify the block below if there are any special requirements.
-->
<p>
......@@ -93,6 +105,8 @@ eventbrite: # FIXME (delete this if not used, otherwise uncomment and provide 12
</p>
<!--
CONTACT EMAIL ADDRESS
Display the contact email address set in the header. If an address
isn't set in the header, the Software Carpentry admin address is
used.
......@@ -111,6 +125,8 @@ eventbrite: # FIXME (delete this if not used, otherwise uncomment and provide 12
<hr/>
<!--
SCHEDULE
Show the workshop's schedule. Edit the items and times in the table
to match your plans. You may also want to change 'Day 1' and 'Day
2' to be actual dates or days of the week.
......@@ -143,9 +159,11 @@ eventbrite: # FIXME (delete this if not used, otherwise uncomment and provide 12
</div>
<!--
Display the Etherpad for the workshop. You will probably set this
up on the first day, so make sure you push changes to GitHub after
you have its URL. To create an Etherpad, go to
ETHERPAD
Display the Etherpad for the workshop. You can set this up in
advance or on the first day; either way, make sure you push changes
to GitHub after you have its URL. To create an Etherpad, go to
http://etherpad.mozilla.org/YYYY-MM-DD-site
......@@ -163,6 +181,8 @@ eventbrite: # FIXME (delete this if not used, otherwise uncomment and provide 12
<hr/>
<!--
SYLLABUS
Show what topics will be covered.
1. If your workshop is R rather than Python, remove the comment
......@@ -254,6 +274,8 @@ eventbrite: # FIXME (delete this if not used, otherwise uncomment and provide 12
<hr/>
<!--