diff --git a/README.md b/README.md index 7dce08d..89fb0dc 100644 --- a/README.md +++ b/README.md @@ -17,18 +17,16 @@ template for creating websites for workshops. We can only do that if you [customize][customization] that page correctly *and* send us a link to your workshop website. -4. Please also read - [the notes on customizing your website][customization] and the [FAQ][faq]. - If you're interested in knowing more about why we do things the way we do, - please check out the [design notes][design]. - -5. If you are teaching Git, - please [create a separate repository](#setting-up-a-separate-repository-for-learners) - for your learners to practice in. - -6. If you run into problems, - or have ideas about how to make this process simpler, - please [get in touch](#getting-and-giving-help). +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. ## Creating a Repository @@ -46,7 +44,7 @@ template for creating websites for workshops. 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`, + e.g., `2016-12-01-miskatonic`, where `YYYY-MM-DD` is the start date of the workshop. 6. Make sure the repository is public. @@ -57,7 +55,8 @@ template for creating websites for workshops. You can now click "Begin Import". When the process is done, - you will receive a message close to "Importing complete! Your new repository julie32/2015-07-01-miskatonic is ready." + you will receive a message like + "Importing complete! Your new repository gvwilson/2016-12-01-miskatonic is ready." and you can go to the new repository by clicking on the name. **Note:** @@ -73,7 +72,7 @@ please [get in touch](#getting-and-giving-help). 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-miskatonic`. + the repository's URL will be `https://github.com/gvwilson/2016-12-01-miskatonic`. 2. Edit the header of `index.html` to customize the list of instructors, workshop venue, etc. @@ -97,30 +96,20 @@ please [get in touch](#getting-and-giving-help). You should specify `-b gh-pages` because the imported repository doesn't have a `master` branch. + In order to view your changes once you are done editing, + you must push to your GitHub repository: + + ~~~ + git push origin gh-pages + ~~~ + **Note:** please do all of your work in your repository's `gh-pages` branch, since [GitHub automatically publishes that as a website][github-project-pages]. -4. The URL for your website is determined automatically based on the URL for your repository: - if your repository is at `https://github.com/your_username/YYYY-MM-DD-site`, - its GitHub Pages website is at `http://your_username.github.io/YYYY-MM-DD-site`. - You must therefore edit the configuration values in `_config.yml` so that: - - 1. `carpentry` is either "dc" (for Data Carpentry) or "swc" (for Software Carpentry). - This determines which logos are loaded. - - 2. `repo` is the name of your GitHub repository, - e.g., `https://github.com/gvwilson/2015-07-01-miskatonic`. - - 3. `root` is the unique identifier of your workshop *with the leading '/'*, - e.g., `/2015-07-01-miskatonic`. - - 4. `email` is the contact email address for your workshop, - e.g., `gvwilson@miskatonic.edu`. - 5. When you are done editing, go to the GitHub Pages URL for your workshop and preview your changes. - In the example above, this is `https://gvwilson.github.io/2015-07-01-miskatonic`. + In the example above, this is `https://gvwilson.github.io/2016-12-01-miskatonic`. **Note:** this template includes some files and directories that most workshops do not need, @@ -143,26 +132,42 @@ you can do so as described below. 2. Run the command: ~~~ - $ jekyll serve --config _config.yml,_config_dev.yml + $ jekyll serve ~~~ and go to to preview your site. You can also run this command by typing `make serve` (assuming you have Make installed). - Note: - the command above uses the values from `_config.yml`, - then overrides some of them with `_config_dev.yml` - so that local files (including CSS style files) will load properly. - Simply running `jekyll serve` will *not* load local files, - so styles and icons may not display properly if you do this. - 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`. +## 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. + ## Installing Software If you want to set up Jekyll @@ -225,6 +230,7 @@ or [mail us][contact]. [issues]: https://github.com/swcarpentry/workshop-template/issues [jekyll]: https://jekyllrb.com/ [jekyll-windows]: http://jekyll-windows.juthilo.com/ +[lesson-example]: https://swcarpentry.github.io/lesson-example/ [pyyaml]: https://pypi.python.org/pypi/PyYAML [ruby-install-guide]: https://www.ruby-lang.org/en/downloads/ [ruby-installer]: http://rubyinstaller.org/