diff --git a/_episodes/01-tooling.md b/_episodes/01-tooling.md index dd30895d53b52e33c2ca8eed0685a6732f4fd5d3..c587970e8c72a8a8ef134b5c8e6729d1c12fd8fb 100644 --- a/_episodes/01-tooling.md +++ b/_episodes/01-tooling.md @@ -116,15 +116,15 @@ The [lesson template]({{ site.template_repo }}) does *not* include `_config.yml` since each lesson will change some of its value, which would result in merge collisions each time the lesson was updated from the template. Instead, -the [template]({{ site.template_repo }}) contains `_config_template.yml`; +the [template]({{ site.template_repo }}) contains `_templates/_config_template.yml`; authors should copy this file to create `_config.yml` and then edit values in the top half. The [template]({{ site.template_repo }}) also contains `_config_dev.yml`, which overrides some settings for use during desktop development. The Makefile that comes with the [template]({{ site.template_repo }}) -adds these values to those in `_config.yml` when running a local server, -so that `make serve` previews the generated site at . +adds these values to those in `_config.yml` when running a local server +(see [below](#previewing)). ## Collections @@ -139,6 +139,22 @@ we store files that appear directly in the navigation bar (rather than under a pulldown menu) in the root directory of the lesson. +## Previewing + +[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 +so that the pages can be previewed. +We strongly recommend using the latter, +since it ensures that inter-page links will work +and extra resources (such as glyph icons) will load properly. + +The Makefile in the root directory of the project has commands for doing both: +`make site` builds files but does not run a server, +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 list of commands. + [github-importer]: https://import.github.com/ [jekyll]: http://jekyllrb.com/ [jekyll-collection]: https://jekyllrb.com/docs/collections/ diff --git a/_episodes/03-organization.md b/_episodes/03-organization.md index 1cc0bf4e509200f6b8094e5db6fd0cf271e3f959..f2fbec64a3d2214183e593fd6b5e14b248d26a7d 100644 --- a/_episodes/03-organization.md +++ b/_episodes/03-organization.md @@ -54,6 +54,19 @@ which should *not* be modified: * `LICENSE.md`: the lesson license. * `Makefile`: commands for previewing the site, cleaning up junk, etc. +## Template Files + +The `_templates` directory contains files that need to be customized for each lesson: + +* `CONTRIBUTING.md`: contribution guidelines. + This file should be copied into the root directory, + and the `issues` and `repo` links at the bottom of the file must be changed + to match the URLs of the lesson. +* `_config.yml`: [Jekyll][jekyll] configuration file. + As explained [earlier]({{ site.root }}/01-tooling/#configuration), + `_templates/_config.yml` must be copied into the root directory + and edited so that its links and other settings are correct for this lesson. + ## Common Files Most lessons will contain the files listed below.