Updating documentation

(and a few other files as well).

The author should then edit the values in the top half of the file.

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

(see [below](#previewing)).

## Collections

If several Markdown files are stored in a directory whose name begins with an underscore,

### `_config.yml`

The [Jekyll][jekyll] configuration file.

This must be edited so that its links and other settings are correct for this lesson:

look for uses of `{USERNAME}`, `{LESSON-NAME}`, `{LESSON-TITLE}`, and `{SITE-NAME}`.

This must be edited so that its links and other settings are correct for this lesson.

*   `carpentry` should be either "dc" (for Data Carpentry) or "swc" (for Software Carpentry).

*   `kind` should be "lesson".

    (The other legal value, "workshop", is used for workshop repositories.)

*   `title` is the title of your lesson,

    e.g.,

    "Defence Against the Dark Arts".

*   `repo` is the URL for your repository on GitHub *without* a trailing slash,

    e.g., `https://github.com/username/subject`.

*   `root` is the last portion of `repo`, with a leading slash.

    For example, if the repository is `https://github.com/username/subject`,

    then `root` must be `/subject`.

*   `email` is the contact email address for the lesson.

### `CITATION`

### `AUTHORS`

A plain text file listing the names and email addresses of the lesson's authors.

A plain text file listing the names of the lesson's authors.

### `index.md`

## Locations and Names

Episode files are stored in `_episodes` so that [Jekyll][jekyll] will create a [collection][jekyll-collection] for them.

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.

This lets us do things like

list each episode's key questions in the syllabus on the lesson home page.

> ## 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

Longer code blocks are formatted by opening and closing the block with `~~~` (three tildes),

with a class specifier after the block:

{% raw %}

    ~~~

    for thing in collection:

        do_something

    ~~~

    {: .source}

{% endraw %}

which is rendered as:

The template includes a Python program to check

whether lesson files conform to our template.

You can run this using `make lesson-check`,

which in turn invokes `bin/lesson_check.py` and `bin/markdown_ast.rb`.

The former is written in Python 3,

and executes all of the checks;

the latter is written in Ruby,

which in turn invokes `bin/markdown_ast.rb` to parse Markdown files

and `bin/lesson_check.py` to check their structure.

The former is written in Ruby,

and uses Jekyll's own Markdown parser (called Kramdown)

so that we are guaranteed to be checking the same dialect of Markdown that Jekyll uses on GitHub.

The latter is written in Python 3,

and executes all of the checks.

The template also includes `bin/repo_check.py`,

which can be invoked by running `make repo-check`.