Lesson Title: Glossary

Key Points

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.

  • 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
  • Edit the .Rmd files not the .md files

  • Run make serve to knit documents and preview lesson website locally

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.


The glossary would go here, formatted as:

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