Filling in standard pages

AUTHORS

+Greg Wilson <gvwilson@software-carpentry.org>

CITATION

+Please cite as:
+
+Greg Wilson (ed.):
+"Software Carpentry Lesson Template."
+Version 5.4, May 2016, https://github.com/gvwilson/new-lesson-tepmlate, DOI pending.

README.md

+lesson-example
+==============
+
+Documentation on the lesson template formatted according to the template's own rules.

_episodes/02-formatting.md

@@ -10,7 +10,12 @@ objectives:
 - "Explain why blockquotes are used to format parts of episodes."
 - "Explain the use of code blocks in episodes."
 keypoints:
-- "FIXME"
+- "Lesson episodes are stored in _episodes/dd-subject.md."
+- "Each episode's title must include a title, time estimates, motivating questions, lesson objectives, and key points."
+- "Episodes should not use sub-headings or HTML layout."
+- "Code blocks can be have the source, regular output, or error class."
+- "Special sections are formatted as blockquotes that open with a level-2 header and close with a class identifier."
+- "Special sections may be callouts or challenges; other styles are used by the template itself."
 ---
 A lesson consists of one or more episodes,
 each of which has:
@@ -129,6 +134,8 @@ 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).
+Each special blockquote must started with a level-2 header,
+but may contain anything after that.
 For example,
 a callout is formatted like this:
 

_episodes/03-organization.md

@@ -16,9 +16,28 @@ We could load these from the web,
 but that would make offline authoring difficult.
 Instead, each lesson's repository is self-contained.
 
-Note: files that appear as top-level items in the navigation menu are stored in the root directory.
-Files that appear under the "extras" menu are stored in the `_extras` directory
-(which is turned into a [Jekyll collection][jekyll-collection] for easier processing).
+> ## Collections
+>
+> As described [earlier]({{ site.root }}/01-tooling/#collections),
+> files that appear as top-level items in the navigation menu are stored in the root directory.
+> Files that appear under the "extras" menu are stored in the `_extras` directory,
+> while lesson episodes are stored in the `_episodes` directory.
+{: .callout}
+
+## Helper Files
+
+As is standard with [Jekyll][jekyll] sites,
+page layouts are stored in `_layouts`
+and snippets of HTML included by these layouts are stored in `_includes`.
+Each of these files includes a comment explaining its purpose.
+
+Authors do not have to specify that episodes use the `episode.html` layout,
+since that is set by the configuration file.
+Pages that authors create should have the `page` layout unless specified otherwise below.
+
+The `assets` directory contains the CSS, Javascript, fonts, and image files
+used in the generated website.
+Authors should not modify these.
 
 ## Standard Files
 
@@ -30,32 +49,90 @@ which should *not* be modified:
 *   `Makefile`: commands for previewing the site, cleaning up junk, etc.
 *   `_extras/contributing.md`: contribution guidelines.
 
-Run `make` on its own to get a list of targets in the Makefile.
-
 ## Common Files
 
-Most lessons will contain the following files which are *not* in the template
-(to avoid repeated merge conflicts):
+Most lessons will contain the files listed below.
+These are *not* included in the template in order to avoid repeated merge conflicts.
 
-*   `AUTHORS`: names and email addresses of authors.
-*   `CITATION`: how the lesson should be cited in publications.
-*   `README.md`: brief description of the lesson displayed by GitHub.
-*   `index.md`: the home page for the lesson (discussed below).
-*   `reference.md`: a reference guide for the lesson (discussed below).
-*   `setup.md`: setup instructions for the lesson (discussed below).
-*   `_extras/discussion.md`: general discussion.
-*   `_extras/guide.md`: the instructors' guide.
+### `README.md`
 
-## Layouts and Inclusions
+A brief description of the lesson that is displayed by GitHub.
+This file does *not* include a [YAML][yaml] header,
+and is *not* included in the generated website.
 
-Page layouts are stored in `_layouts`,
-while snippets of HTML included by these layouts are stored in `_includes`,
-because that's what [Jekyll][jekyll] requires.
+### `AUTHORS`
 
-## Assets
+The names and email addresses of authors, one per line.
+This file is used to map Git contributions to real identities when the lesson is published.
 
-The `assets` directory contains the CSS, Javascript, fonts, and image files
-used in the generated website.
+### `CITATION`
+
+This explains how the lesson should be cited in publications.
+
+### `index.md`
+
+The home page for the lesson.
+
+1.  It must use the `index` layout.
+2.  It must *not* have a `title` field in its [YAML][yaml] header.
+3.  It must open with a few paragraphs of explanatory text.
+4.  That introduction must be followed by a single `.prereq` blockquote
+    detailing the lesson's prerequisites.
+    (Setup instructions appear separately.)
+5.  That must be followed by inclusion of `syllabus.html`,
+    which generates the syllabus for the lesson
+    from the metadata in its episodes.
+
+### `reference.md`
+
+A reference guide for the lesson.
+
+1.  It must use the `reference` layout.
+2.  Its title must be `"Reference"`.
+3.  Its permalink must be `/reference/`.
+4.  It should include a glossary, laid out as a description list.
+5.  It may include other material as appropriate.
+
+The template will automatically generate a summary of the episodes' key points.
+
+### `setup.md`
+
+Detailed setup instructions for the lesson.
+
+1.  It must use the `page` layout.
+2.  Its title must be `"Setup"`.
+3.  Its permalink must be `/setup/`.
+4.  It should include whatever setup instructions are required.
+
+Note that we usually divide setup instructions by platform,
+e.g.,
+include level-2 headings for Windows, Mac OS X, and Linux
+with instructions for each.
+The [workshop template]({{ site.workshop_repo }})
+links to the setup instructions for core lessons.
+
+### `_extras/discussion.md`
+
+General discussion of the lesson contents for learners who wish to know more:
+
+1.  It must use the `page` layout.
+2.  Its title must be `"Discussion"`.
+3.  Its permalink must be `/discuss/`.
+4.  It may include whatever content the author thinks appropriate.
+
+This page normally includes links to further reading
+and/or brief discussion of more advanced topics.
+
+### `_extras/guide.md`
+
+The instructors' guide for the lesson.
+
+1.  It must use the `page` layout.
+2.  Its title must be `"Instructors' Guide"`.
+3.  Its permalink must be `/guide/`.
+4.  It may include whatever content the author thinks appropriate.
+
+This page records tips and warnings from people who have taught the lesson.
 
 [jekyll]: http://jekyllrb.com/
 [jekyll-collection]: https://jekyllrb.com/docs/collections/

_extras/discussion.md

+---
+layout: page
+title: Discussion
+permalink: /discuss/
+---
+FIXME: general discussion.

_extras/guide.md

+---
+layout: page
+title: "Instructors' Guide"
+permalink: /guide/
+---
+FIXME: instructors' guide.