diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index 23fd1f45cf99abb0f866ddca7a8333b5e5dab721..1589a191a7d7bdde74cc5903c625053662a82614 100644 --- a/CONTRIBUTING.md +++ b/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 diff --git a/_episodes/01-tooling.md b/_episodes/01-tooling.md index 708e47d4ab937d505bb3e70132a5f4370b590946..d29cdaf0752e5f169227c0c9082cbd2d35ad2f31 100644 --- a/_episodes/01-tooling.md +++ b/_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/ diff --git a/setup.md b/setup.md index 62b6e87e55540b173e3cab1edabbc23332f37b0b..54b0f6b05a414a693d3d745efecb3de64dac044e 100644 --- a/setup.md +++ b/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.