Formatting lessons

_episodes/01-tooling.md

@@ -91,7 +91,7 @@ Values from the header are referred to in the page as `page.variable`.
 
 ## Configuration
 
-Jekyll also reads values from a configuration file called `_config.yml`,
+[Jekyll][jekyll] also reads values from a configuration file called `_config.yml`,
 which are referred to in the page as `site.variable`.
 The [lesson template]({{ site.template_repo }}) does *not* include `_config.yml`,
 since each lesson will change some of its value,
@@ -106,8 +106,16 @@ 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.
 
+## Collections
+
+If several Markdown files are stored in a directory whose name begins with an underscore,
+[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`).
+
 [github-importer]: https://import.github.com/
 [jekyll]: http://jekyllrb.com/
+[jekyll-collection]: https://jekyllrb.com/docs/collections/
 [jupyter]: https://jupyter.org/
 [r-markdown]: http://rmarkdown.rstudio.com/
 [rstudio]: https://www.rstudio.com/

_episodes/02-formatting.md

@@ -12,18 +12,120 @@ objectives:
 keypoints:
 - "FIXME"
 ---
+A lesson consists of one or more episodes,
+each of which has:
+
+*   a title
+*   time estimates for teaching and exercises
+*   motivating questions
+*   lesson objectives
+*   teachable content
+*   exercises
+*   a summary of key points
+
+## Locations and Names
+
+Episode files are stored in `_episodes` so that [Jekyll][jekyll] will create a [collection][jekyll-collection] for them.
+Episodes are named `dd-subject.md`,
+where `dd` is a two-digit sequence number (with a leading 0)
+and `subject` is a one- or two-word identifier.
+For example,
+the episodes of this example lesson are
+`_episodes/01-tooling.md`
+`_episodes/02-formatting.md`,
+and `_episodes/03-organization.md`,
+which become `/01-tooling/`, `/02-formatting/`, and `/03-organization/` respectively.
+(The episode files are turned into `index.html` files in an appropriately-named sub-directory of the generated site.)
+
 ## Episode Header
 
-FIXME
+The episode's title, times, questions, objectives, and key points are all specified in its header
+so that [Jekyll][jekyll] can access them.
+For example,
+if a motivating question in an episode is changed,
+it will automatically be updated in the lesson's home page
+as well as the episode's page.
+
+Note that Markdown in YAML values in the header is *not* rendered when the value is used elsewhere.
 
 ## Episode Structure
 
-FIXME
+The episode layout template in `_layouts/episode.html` automatically creates
+an introductory block that summarizes the lesson
+and a closing block that lists its key points.
+In between,
+authors should use only:
+
+*   paragraphs
+*   images
+*   tables
+*   ordered and unordered lists
+*   special blockquotes (described below)
+*   code samples (described below).
+
+Authors should *not* use:
+
+*   sub-headings
+*   HTML layout (e.g., `div` elements).
 
 ## Special Blockquotes
 
-FIXME
+We use blockquotes to group headings and text
+rather than wrapping them in `div` elements.
+For example,
+a callout is formatted like this:
+
+~~~
+> ## Callout Title
+>
+> text
+> text
+> text
+> ~~~
+> code
+> ~~~
+{: .callout}
+~~~
+
+The key part of this is the class specified at the bottom:
+an opening curly brace and colon,
+the class identifier with a leading dot,
+and a closing curly brace.
+The [lesson template]({{ site.template_repo }}) defines styles
+for the following special blockquotes:
+
+*   `.callout`: an aside or other comment.
+*   `.challenge`: an exercise.
+*   `.getready`: preparatory material.
+*   `.keypoints`: key points of an episode.
+*   `.objectives`: episode objectives.
+*   `.prereq`: lesson prerequisites.
+*   `.testimonial`: a laudatory quote from a user.
+
+Most authors will only use `.callout` and `.challenge`,
+as the others are automatically generated by the template.
 
 ## Formatting Code
 
-FIXME
+Inline code fragments are formatted using back-quotes.
+Longer code blocks are formatted by opening and closing the block with `~~~` (three tildes),
+with a class specifier after the block:
+
+    ~~~
+    for thing in collection:
+        do_something
+    ~~~
+    {: .source}
+
+The [template]({{ site.template_repo }}) provides three styles for code blocks:
+
+*   `.error`: error messages.
+*   `.output`: program output.
+*   `.source`: program source.
+
+We do not use syntax highlighting for code blocks
+because most learners either don't have it,
+or have it set to colorize differently than we would.
+
+[jekyll]: http://jekyllrb.com/
+[jekyll-collection]: https://jekyllrb.com/docs/collections/