Using Markdown

Last updated on 2022-11-10 | Edit this page

Estimated time: 12 minutes

Overview

Questions

  • How do you write a lesson using Markdown and sandpaper?

Objectives

  • Explain how to use markdown with The Carpentries Workbench
  • Demonstrate how to include pieces of code, figures, and nested challenge blocks

Introduction

From e-mail

Structure Zotero with Master- and PhD students:

  • Refresher on academic referencing, why it’s important to cite correctly, and basic citation formats
  • Information on reference management software in general (what it can do and why you should use it)
  • Choice of reference management software (i.e. the advantages of zotero, comparison to others)
  • Using Zotero:

SH 

*	Basic workflow (browser button and word plugin)
*	Other outputs (citation styles, copy to clipboard, adjust in word, export formats, …)
*	Other inputs - single items (eg from doi, from file, manual, …)
*	Other inputs - multiple items (eg from database, drag and drop, …)
*	Organizing your library (notes, tags, folders, …)
*	Getting the most out of zotero (shared libraries, proxy settings, retraction watch, sync & storage, addons,  …)

Suggest to put most of these except maybe the last point into the ‘basics’ for the first 3 hours, then we would need some structure for the afternoon part as well. Maybe we can merge that somehow with P‘s ideas to organize by activities, e.g. writing, reading, literature searches, etc.

This is a lesson created via The Carpentries Workbench. It is written in Pandoc-flavored Markdown for static files and R Markdown for dynamic files that can render code into output. Please refer to the Introduction to The Carpentries Workbench for full documentation.

What you need to know is that there are three sections required for a valid Carpentries lesson:

  1. questions are displayed at the beginning of the episode to prime the learner for the content.
  2. objectives are the learning objectives for an episode displayed with the questions.
  3. keypoints are displayed at the end of the episode to reinforce the objectives.

Inline instructor notes can help inform instructors of timing challenges associated with the lessons. They appear in the “Instructor View”

Challenge 1: Can you do it?

What is the output of this command?

R 

paste("This", "new", "lesson", "looks", "good")

OUTPUT 

[1] "This new lesson looks good"

Challenge 2: how do you nest solutions within challenge blocks?

You can add a line with at least three colons and a solution tag.

Figures

You can use standard markdown for static figures with the following syntax:

![optional caption that appears below the figure](figure url){alt='alt text for accessibility purposes'}

Blue Carpentries hex person logo with no text.
You belong in The Carpentries!

Math

One of our episodes contains \(\LaTeX\) equations when describing how to create dynamic reports with {knitr}, so we now use mathjax to describe this:

$\alpha = \dfrac{1}{(1 - \beta)^2}$ becomes: \(\alpha = \dfrac{1}{(1 - \beta)^2}\)

Cool, right?

Key Points

  • Use .md files for episodes when you want static content
  • Use .Rmd files for episodes when you need to generate output
  • Run sandpaper::check_lesson() to identify any issues with your lesson
  • Run sandpaper::build_lesson() to preview your lesson locally