# Lesson Title

## Key Points

Lesson Design

- Lessons are design in four stages: conceptual, summative, formative, and connective.

GitHub, Markdown, and Jekyll

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

Lesson Organization

- Auxiliary files are stored in the _layouts, _includes, and assets directories.

- The code of conduct, license, Makefile, and contribution guidelines should not be modified.

- The README, authors’ list, and citation instructions must be updated for each lesson.

- The home page, reference guide, setup instructions, discussion page, and instructors’ guide must be updated for each lesson.

- The Makefile stores commonly-used commands.

Formatting

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

Checking and Previewing

- Lessons are checked by running `make lesson-check`.

- The checker uses the same Markdown parser as Jekyll.

- Lessons can be previewed by running `make serve`.

Using RMarkdown

- It shouldn’t be difficult

Maintenance

- Each lesson has one or two maintainers who act as editors.

- Maintainers are responsible for ensuring that issues and change requests are addressed.

- Maintainers have final say over lesson content.

- We use a standard set of labels to classify issues and pull requests.

## Glossary

The glossary would go here, formatted as:

    {:auto_ids}
    key word 1
    :   explanation 1

    key word 2
    :   explanation 2

(`{:auto_ids}` is needed at the start so that Jekyll will automatically generate a unique ID for each item to allow other pages to hyperlink to specific glossary entries.) This renders as:

key word 1
  explanation 1
key word 2
  explanation 2