|
Lesson Design
|
|
|
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-titles 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.
|
|
Using RMarkdown
|
|
|
Style Guide
|
The Carpentries Handbook contains a style guide.
Keyboard actions are described using the <kbd> HTML tag.
A backtick (`) indicates a span of code and is used to enclose code excerpts, segments of text to type, and filenames within in narrative text.
|
|
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.
|
{:auto_ids}
key word 1
: explanation 1
key word 2
: explanation 2