Explaining how to set up for lesson development

CONTRIBUTING.md

@@ -111,6 +111,8 @@ and have final say over what gets merged into the lesson.
 
 [This documentation][example-site] explains how we format our lessons
 (and is itself an example of that formatting).
+The episode on tooling explains
+[how to check and preview changes]({{ site.root }}/01-tooling/#checking-and-previewing).
 
 ## Other Resources
 

_episodes/01-tooling.md

@@ -168,26 +168,17 @@ we store files that appear directly in the navigation bar
 in the root directory of the lesson.
 [The last episode]({{ site.root }}/03-organization/) describes these files.
 
-## Installing
+## Checking and Previewing
 
-You can preview changes by pushing to the `gh-pages` branch of your own repository,
-but it's often easier to view them locally first.
-To do that,
-you will need to install [Jekyll][jekyll] and a few other packages used by GitHub Pages.
-The easiest way to do that is:
-
-1.  Install Ruby if you don't already have it.
-2.  Install Ruby Gems (Ruby's package manager).
-3.  `gem install github-pages` (which will give you Jekyll and things it depends on).
-
-See [the Jekyll installation documentation][jekyll-install]
-for full instructions.
-
-## Previewing
+The lesson template includes a Python program to check
+whether lesson files conform to our template.
+You can run this using `make lesson-check`.
+It relies on a small Ruby script that uses Jekyll's own Markdown parser (called Kramdown)
+so that we are guaranteed to be checking the same dialect of Markdown that Jekyll uses on GitHub.
 
 [Jekyll][jekyll] can be used in two ways:
 to compile source files into HTML pages in the `_site` directory,
-or to do that and also run a small web server at <http://127.0.0.1:4000/>
+or to do that and also run a small web server at <http://0.0.0.0:4000/>
 so that the pages can be previewed.
 We recommend using the latter,
 since it gives a more accurate impression of what your lesson will actually look like.
@@ -198,6 +189,10 @@ while `make serve` builds the files and runs a server.
 (It also re-builds the site whenever it notices changes in the source files.)
 Run `make` on its own to get a full list of commands.
 
+In order to use Jekyll and/or the checking script,
+you may need to install it and some other software.
+The [setup instructions]({{ site.root }}/setup/) explain what you need and how to get it.
+
 [github-importer]: https://import.github.com/
 [jekyll]: http://jekyllrb.com/
 [jekyll-collection]: https://jekyllrb.com/docs/collections/

setup.md

@@ -3,14 +3,17 @@ layout: page
 title: Setup
 permalink: /setup/
 ---
+## Setup Instructions for Actual Lessons
+
 1. Installation instructions for core lessons are included in the [workshop template's home page][template],
    so that they are all in one place.
-   The `setup.md` files of core lessons link to the appropriate sections of the [workshop template page][template].
+   The `setup.md` files of core lessons link to
+    the appropriate sections of the [workshop template page][{{ site.workshop_repo }}].
 
 2. Other lessons' `setup.md` include full installation instructions organized by OS
    (following the model of the workshop template home page).
 
---------
+## Setting Up for Lesson Development
 
 If you want to set up Jekyll
 so that you can preview changes on your own machine before pushing them to GitHub,
@@ -31,4 +34,6 @@ you must install the software described below.
 3.  **[Jekyll](https://jekyllrb.com/)**.
     You can install this by running `gem install jekyll`.
 
-[template]: {{ site.workshop_repo }}
+If you want to run `bin/check-lesson` (which is invoked by `make lesson-check`)
+you will need Jekyll (so that you have its Markdown parser, which is called Kramdown)
+and the [PyYAML](https://pypi.python.org/pypi/PyYAML) module for Python 3.