diff --git a/_episodes/01-tooling.md b/_episodes/01-tooling.md index ab7d78f1382b4aa225db595bba68ab17a22c96cb..300144aa9bdd579b3793b63984d308f7cadd67ab 100644 --- a/_episodes/01-tooling.md +++ b/_episodes/01-tooling.md @@ -8,7 +8,12 @@ objectives: - "Explain how GitHub Pages produce web sites from Git repositories." - "Explain Jekyll's formatting rules." keypoints: -- "FIXME" +- "Lessons are stored in Git repositories on GitHub." +- "Lessons are written in Markdown." +- "Jekyll translates the files in the gh-pages branch into HTML for viewing." +- "The site's configuration is stored in _config.yml." +- "Each page's configuration is stored at the top of that page." +- "Groups of files are stored in collection directories whose names begin with an underscore." --- This episode describes tools we use to manage lessons, which simplify many tasks but make other things more complicated. @@ -37,27 +42,31 @@ to update the lesson when the template changes. If a repository has a branch called `gh-pages` (short for "GitHub Pages"), GitHub publishes its content to create a website for the repository. +Websites can be static HTML pages, +which are published as-is, +or can use [Jekyll][jekyll] as described below. If the repository's URL is `https://github.com/USERNAME/REPOSITORY`, the website is `https://USERNAME.github.io/REPOSITORY`. -Websites can be static HTML pages, -which are published as-is, -or can use the [Jekyll][jekyll] templating system described below. +> ## Why Doesn't My Site Appear? +> +> If the root directory of a repository contains a file called `.nojekyll`, +> GitHub will *not* generate a website for that repository's `gh-pages` branch. ## Markdown -We use Markdown for lesson content because it's simple to learn -and isn't tied to any specific language -(the ReStructured Text format popular in the Python world, +We write lessons in Markdown because it's simple to learn +and isn't tied to any specific language. +(The ReStructured Text format popular in the Python world, for example, -is a complete unknown to R programmers). -If authors want to use something else to author their lessons, +is a complete unknown to R programmers.) +If authors want to write lessons in something else, such as [R Markdown][r-markdown], -they must generate Markdown that [Jekyll][jekyll] can process, -or static HTML, +they must generate HTML or Markdown that [Jekyll][jekyll] can process and commit that to the repository. +The [next episode]({{ site.root }}/02-formatting/) describes the Markdown we use. -> ## Tooling +> ## Teaching Tools > > We do *not* prescribe what tools instructors should use when actually teaching: > the [Jupyter Notebook][jupyter], @@ -85,14 +94,23 @@ and inserts the values of those variables into the page when formatting this. The three dashes that start the header *must* be the first three characters in the file: even a single space before them will make [Jekyll][jekyll] ignore the file. -Jekyll requires the header to be formatted as [YAML][yaml], -which provides Booleans, numbers, character strings, lists, and dictionaries of name/value pairs. +The header must be formatted as [YAML][yaml], +and may contain Booleans, numbers, character strings, lists, and dictionaries of name/value pairs. Values from the header are referred to in the page as `page.variable`. +> ## Back in the Day... +> +> The previous version of our template did not rely on Jekyll, +> but instead required authors to build HTML on their desktops +> and commit that to the lesson repository's `gh-pages` branch. +> This allowed us to use whatever mix of tools we wanted for creating HTML (e.g., [Pandoc][pandoc]), +> but complicated the common case for the sake of uncommon cases, +> and didn't model the workflow we want learners to use. + ## Configuration [Jekyll][jekyll] also reads values from a configuration file called `_config.yml`, -which are referred to in the page as `site.variable`. +which are referred to in pages as `site.variable`. 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. @@ -104,7 +122,8 @@ 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. +adds these values to those in `_config.yml` when running a local server, +so that `make serve` previews the generated site at . ## Collections @@ -112,11 +131,18 @@ If several Markdown files are stored in a directory whose name begins with an un [Jekyll][jekyll] creates a [collection][jeyll-collection] for them. We rely on this for both lesson episodes (stored in `_episodes`) and extra files (stored in `_extras`). +For example, +putting the extra files in `_extras` allows us to populate the "Extras" menu pulldown automatically. +To make this clear, +we store files that appear directly in the navigation bar +(rather than under a pulldown menu) +in the root directory of the lesson. [github-importer]: https://import.github.com/ [jekyll]: http://jekyllrb.com/ [jekyll-collection]: https://jekyllrb.com/docs/collections/ [jupyter]: https://jupyter.org/ +[pandoc]: https://pandoc.org/ [r-markdown]: http://rmarkdown.rstudio.com/ [rstudio]: https://www.rstudio.com/ [yaml]: http://yaml.org/