generated from carpentries/workbench-template-md
-
Notifications
You must be signed in to change notification settings - Fork 3
Commit
This commit does not belong to any branch on this repository, and may belong to a fork outside of the repository.
Showing
1 changed file
with
17 additions
and
93 deletions.
There are no files selected for viewing
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Original file line number | Diff line number | Diff line change |
---|---|---|
@@ -1,114 +1,38 @@ | ||
--- | ||
title: "Using Markdown" | ||
title: "IPCC FAIR Background" | ||
teaching: 10 | ||
exercises: 2 | ||
--- | ||
|
||
:::::::::::::::::::::::::::::::::::::: questions | ||
|
||
- How do you write a lesson using Markdown and `{sandpaper}`? | ||
- What are the fundamentals to produce a FAIR IPCC Assessemt Report`? | ||
|
||
:::::::::::::::::::::::::::::::::::::::::::::::: | ||
|
||
::::::::::::::::::::::::::::::::::::: objectives | ||
|
||
- Explain how to use markdown with The Carpentries Workbench | ||
- Demonstrate how to include pieces of code, figures, and nested challenge blocks | ||
- Learn the FAIR priniciples and motivations | ||
- Learn about genereal Research Data and Software Management Practices | ||
- Learn about story telling and visualisation | ||
|
||
:::::::::::::::::::::::::::::::::::::::::::::::: | ||
|
||
## Introduction | ||
## FAIR data principles at IPCC | ||
motivation for archiving code, figures, input data and metadata | ||
[FAIR guidance](https://zenodo.org/records/10039597) | ||
|
||
This is a lesson created via The Carpentries Workbench. It is written in | ||
[Pandoc-flavored Markdown](https://pandoc.org/MANUAL.txt) for static files and | ||
[R Markdown][r-markdown] for dynamic files that can render code into output. | ||
Please refer to the [Introduction to The Carpentries | ||
Workbench](https://carpentries.github.io/sandpaper-docs/) for full documentation. | ||
## The experience in AR6 and shortcomings | ||
|
||
What you need to know is that there are three sections required for a valid | ||
Carpentries lesson: | ||
including some examples. | ||
|
||
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. | ||
|
||
:::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::: instructor | ||
## Fundamentals of Sustainable Research Software | ||
Software Management Plans | ||
[eScience](https://www.esciencecenter.nl/wp-content/uploads/2023/01/SS-2023-3.-Template-Software-Management-Plan-2023.docx) | ||
|
||
Inline instructor notes can help inform instructors of timing challenges | ||
associated with the lessons. They appear in the "Instructor View" | ||
## Fundamentals of Research Data Management | ||
[The Turing way Tutorial](https://book.the-turing-way.org/reproducible-research/rdm.html) | ||
|
||
:::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::: | ||
|
||
::::::::::::::::::::::::::::::::::::: challenge | ||
|
||
## Challenge 1: Can you do it? | ||
|
||
What is the output of this command? | ||
|
||
```r | ||
paste("This", "new", "lesson", "looks", "good") | ||
``` | ||
|
||
:::::::::::::::::::::::: solution | ||
|
||
## Output | ||
|
||
```output | ||
[1] "This new lesson looks good" | ||
``` | ||
|
||
::::::::::::::::::::::::::::::::: | ||
|
||
|
||
## Challenge 2: how do you nest solutions within challenge blocks? | ||
|
||
:::::::::::::::::::::::: solution | ||
|
||
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'}` | ||
|
||
![You belong in The Carpentries!](https://raw.githubusercontent.com/carpentries/logo/master/Badge_Carpentries.svg){alt='Blue Carpentries hex person logo with no text.'} | ||
|
||
::::::::::::::::::::::::::::::::::::: callout | ||
|
||
Callout sections can highlight information. | ||
|
||
They are sometimes used to emphasise particularly important points | ||
but are also used in some lessons to present "asides": | ||
content that is not central to the narrative of the lesson, | ||
e.g. by providing the answer to a commonly-asked question. | ||
|
||
:::::::::::::::::::::::::::::::::::::::::::::::: | ||
|
||
|
||
## 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? | ||
|
||
::::::::::::::::::::::::::::::::::::: keypoints | ||
|
||
- 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 | ||
|
||
:::::::::::::::::::::::::::::::::::::::::::::::: | ||
|
||
[r-markdown]: https://rmarkdown.rstudio.com/ | ||
## Models of interactive products: | ||
Storytelling, layered storytelling, static vs dynamic, GIS-based models. |