diff --git a/_episodes/01-tooling.md b/_episodes/01-tooling.md
index 300144aa9bdd579b3793b63984d308f7cadd67ab..e6080b6d8f68522dfb6ced2bd7e97049c90722be 100644
--- a/_episodes/01-tooling.md
+++ b/_episodes/01-tooling.md
@@ -52,6 +52,7 @@ the website is `https://USERNAME.github.io/REPOSITORY`.
 >
 > 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.
+{: .callout}
 
 ## Markdown
 
@@ -106,6 +107,7 @@ Values from the header are referred to in the page as `page.variable`.
 > 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.
+{: .callout}
 
 ## Configuration
 
diff --git a/_episodes/02-formatting.md b/_episodes/02-formatting.md
index 812cede016a7bf01c6294d992ebec90a1c0888cc..498d4700cba5892e434feb214d98998e3c16c106 100644
--- a/_episodes/02-formatting.md
+++ b/_episodes/02-formatting.md
@@ -15,13 +15,9 @@ keypoints:
 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
+*   a [YAML][yaml] header containing required values
+*   some teachable content
+*   some exercises
 
 ## Locations and Names
 
@@ -33,26 +29,49 @@ 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.)
+and `_episodes/03-organization.md`.
+These become `/01-tooling/`, `/02-formatting/`, and `/03-organization/` respectively in the published site
+(the episode file `dd-subject.md` is turned into `dd-subject/index.html`).
+When referring to other episodes, use:
+
+{% raw %}
+    [link text]({{ site.root }}/dd-subject/)
+{% endraw %}
+
+i.e., use the episode's directory path below the site root.
+This will ensure that the link is valid both when previewing during desktop development
+and when the site is published on GitHub.
 
 ## Episode Header
 
-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.
+Each episode's [YAML][yaml] header must contain:
+
+*   the episode's title
+*   time estimates for teaching and exercises
+*   motivating questions
+*   lesson objectives
+*   a summary of key points
+
+These values are stored in the header so that [Jekyll][jekyll] will read them
+and make them accessible in other pages as `site.episodes.the_episode.key`,
+where `the_episode` is the particular episode
+and `key` is the key in the [YAML][yaml] header.
+This lets us do things like
+list each episode's key questions in the syllabus on the lesson home page.
 
-Note that Markdown in YAML values in the header is *not* rendered when the value is used elsewhere.
+> ## Raw Text
+>
+> Markdown in YAML values in the header is *not* rendered when the value is used elsewhere.
+{: .callout}
 
 ## Episode Structure
 
 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.
+an introductory block that summarizes the lesson's teaching time,
+exercise time,
+key questions,
+and objectives.
+It also automatically creates a closing block that lists its key points.
 In between,
 authors should use only:
 
@@ -60,18 +79,56 @@ authors should use only:
 *   images
 *   tables
 *   ordered and unordered lists
-*   special blockquotes (described below)
 *   code samples (described below).
+*   special blockquotes (described below)
 
 Authors should *not* use:
 
 *   sub-headings
 *   HTML layout (e.g., `div` elements).
 
+## Formatting Code
+
+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}
+
+which is rendered as:
+
+~~~
+for thing in collection:
+    do_something
+~~~
+{: .source}
+
+The class specified at the bottom using an opening curly brace and colon,
+the class identifier with a leading dot,
+and a closing curly brace.
+The [template]({{ site.template_repo }}) provides three styles for code blocks:
+
+*   `.error`: error messages.
+*   `.output`: program output.
+*   `.source`: program source.
+
+> ## Why No Syntax Highlighting?
+>
+> We do not use syntax highlighting for code blocks
+> because some learners's systems won't do it,
+> or will do it differently than what they see on screen.
+{: .callout}
+
 ## Special Blockquotes
 
 We use blockquotes to group headings and text
 rather than wrapping them in `div` elements.
+in order to avoid confusing [Jekyll][jekyll]'s parser
+(which sometimes has trouble with Markdown inside HTML).
 For example,
 a callout is formatted like this:
 
@@ -81,16 +138,27 @@ a callout is formatted like this:
 > 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.
+(Note the empty lines within the blockquote after the title and before the code block.)
+This is rendered as:
+
+> ## Callout Title
+>
+> text
+> text
+> text
+>
+> ~~~
+> code
+> ~~~
+{: .callout}
+
 The [lesson template]({{ site.template_repo }}) defines styles
 for the following special blockquotes:
 
@@ -105,27 +173,6 @@ for the following special blockquotes:
 Most authors will only use `.callout` and `.challenge`,
 as the others are automatically generated by the template.
 
-## Formatting Code
-
-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/
+[yaml]: http://yaml.org/