Transition Guide: From Styles to Workbench

This document is intended to provide you with a quick reference about the differences between kramdown (used by styles) and pandoc-flavoured markdown (used by The Workbench):

Default Branch

Workbench

The default branch is always main

styles

The default branch is gh-pages UNLESS you have rendered RMarkdown content, then the default branch is main

Infrastructure

Workbench

The workbench infrastructure is independent¹ from individual lessons. It consists of three major pieces of software.

Git
R
Pandoc

The workbench itself consists of three R packages, which can all be updated on the fly with no changes to the lesson.

{sandpaper}: user interface and workflow engine
{pegboard}: parsing and validation engine
{varnish}: HTML templates, CSS, and JS elements

styles

The styles infrastructure is embedded within the lesson itself. It requires the following major pieces of software to run:

Git
Ruby
BASH
Make
Python²
R³

The styles workflow is a Jekyll-based workflow, which uses the following components:

bundler: manages the Ruby gems (packages) including Jekyll
Jekyll: static site generator
(file) Makefile: workflow management for building and validating
(dir) assets/: CSS and JS elements
(dir) _layouts/: HTML templates
(dir) bin/: intialisation, runtime, and validation scripts (in BASH, Python, and R)
(dir) _includes/: Markdown and HTML boilerplate for customisation

The file components can only be updated via pull request.

Local Rendering

Workbench

If you haven’t already, Follow the setup instructions for the workbench to install R, pandoc, and the workbench packages
In your lesson directory, open either R, RStudio, or VS Code and run:

sandpaper::serve()

styles

If you haven’t already, Follow the setup instructions for styles to install Ruby, Bundler, Jekyll, Make, Python, and BASH
In your lesson directory, open your command line and run:

make serve

Folder Structure

The folders from styles to Workbench are rearranged to achieve the following goals:

tools for building the lesson do not live in the lesson ⁴.
the episodes can be directly lifted from the lesson without needing external context/resources.
extra content intended for instructors is clearly separated from that intended for learners

Episodes (aka Chapters) will move from _episodes/ and _episodes_rmd to the single folder episodes/. _extras/ content will be split into learners/ and instructors/ depending on the context of the content. Figures, data, and files all become subfolders of episodes/.

Callout Blocks/Special Blockquotes

Workbench

A callout block with The Workbench uses at least three colons followed by a keyword to start a block. The block is closed with at least three colons.

Note

You can find a demonstration of all the possible callout blocks in the workbench component guide

:::: callout

### Act Openly

We believe that transparency, honesty, and fairness are keys to fostering
trust within an open community.

::::::::::::

Tip

These are called fenced divs and in Workbench lessons, you will often see them have many more colons to clearly delineate sections in a lesson. The number of opening colons and the number of closing colons do not match and it is completely up to the lesson author to choose a style.

styles

A callout block (aka “Special Blockquote”) with styles used block quote syntax and level 2 headers followed by a postfix tag declaring the class of block

Note

You can find a demonstration of all the possible callout blocks in the styles “Special Blockquotes” guide

> ## Act Openly
>
> We believe that transparency, honesty, and fairness are keys to fostering
> trust within an open community.
>
{: .callout}

Did you know?

The decision to use blockquotes was to facilitate an easy way to author special sections without having lesson authors/contributors type <div> tags into the document.

Highlighted Code Blocks

Workbench

Code fences in the workbench are indicated by fences that consist of three backticks (```) with the name of the language appended on the opening fence:

clean all merged branches from git

```bash
git branch --merged | grep -v '^\*' | xargs git branch -d
```

styles

Code fences in styles follow kramdown syntax, which prefers fences that consist of three tildes (~~~) with the liquid tag of the language appended on a new line after the closing fence (postfix tag):

clean all merged branches from git

~~~
git branch --merged | grep -v '^\*' | xargs git branch -d
~~~
{: .language-bash}

Challenge/Solution blocks

Workbench

The challenge and solution blocks in the workbench are nested pairs of blocks with an optional Level 3 header. You can additonally add a “hint” block before the solution.

::::::::::::::::::::::::::::: challenge

### Challenge: build

What is the R command to build a Workbench lesson?

::::::: hint

This command is going to start a **serve**r on your computer

:::::::::::::

::::::::: solution

```r
sandpaper::serve()
```

::::::::::::::::::
:::::::::::::::::::::::::::::::::::::::

Tip

To help distinguish sections, double the number of columns for the outer section compared to the inner section.

styles

The challenge and solution blocks in the workbench are nested block quotes with Level 2 headers. Additional blocks are still of the class “solution”

> ## Challenge: build
> 
> What is the R command to build a Workbench lesson?
> 
> > ## Hint
> >
> > This command is going to start a **serve**r on your computer
> > 
> {: .solution} 
>
> > ~~~
> > sandpaper::serve()
> > ~~~
> > {: .language-r}
> {: .solution} 
{: .challenge}

Questions/Objectives/Keypoints

Workbench

Questions and Objectives appear at the top of the lesson as fenced divs with list elements:

---
title: "Bomp"
teaching: 5
exercises: 5
---

::::::::::::::::: questions

 - Who put the **bomp** in the bomp bah bomp bah bomp?
 - Who put the **ram** in the rama lama ding dong?

:::::::::::::::::::::::::::

::::::::::::::::: objectives

 - Solve the "bomp" mystery.

::::::::::::::::::::::::::::

## Introduction

...

Keypoints should go in a fenced div at the end of the document:

...

::::::::::::::::: keypoints

 - We will never know who put the bomp in the bomp bah bomp bah bomp.

:::::::::::::::::::::::::::

styles

The questions, objectives, and keypoints were placed in the YAML metadata for each episode:

---
title: "Bomp"
teaching: 5
exercises: 5
questions:
 - "Who put the bomp in the bomp bah bomp bah bomp?"
 - "Who put the ram in the rama lama ding dong?"
objectives:
 - "Solve the \"bomp\" mystery."
keypoints:
 - "We will never know who put the bomp in the bomp bah bomp bah bomp." 
---

## Introduction

...

The trouble with YAML metadata

It was not possible to include markdown inside these strings and it often caused errors due to missed quotation marks (i.e. - "sentence with a period after quotes". was a common type of error.)

This content was originally introduced into the YAML metadata so that we could use Jekyll’s metadata parsing to create a custom introductory block.

Instructor notes

Workbench

An inline instructor note in the workbench is formed inside an episode by making a fenced div with the class “instructor”

:::: instructor

Here be dragons

::::::::::::

Instructor notes for the whole lesson can be placed in instructors/instructor-notes.md

styles

Instructor notes do not exist in styles other than an aggregate markdown file called _extras/guide.md

Internal Links

Workbench

Links in the Workbench are relative to the file so that you can link to the files and confirm they work in the github preview. Figures, files, and data are nested inside the episodes/ folder.

<!-- Next Episode -->
[next episode on dragons](dragons.md)
<!-- Data -->
[download the dragon data for this episode](data/dragon-lifespan.csv)
<!-- Setup -->
[setup instructions](../learners/setup.md)

styles

Links are relative to the page that they are rendered to. You should use the {{ page.root }} variable and the link tag in order to construct the correct path to the resource:

<!-- Next Episode -->
[next episode on dragons]({{ page.root }}{% link _episodes/dragons.md %})
<!-- Data -->
[download the dragon data for this episode]({{ page.root }}/data/dragon-lifespan.csv)
<!-- Setup -->
[setup instructions]({{ page.root }}/setup.md)

Figures

Workbench

Figures are written with the caption in the square brackets and alt appended as an attribute like so: ![caption](fig/image.png){alt='image description'}.

![The dragon emerges!](fig/dragon-egg.png){alt='a red baby 
dragon head sticks out from its egg'}

Note

There is a valid reason behind this choice: text inside of the square brackets can be formatted as markdown, so it makes sense for the caption. Alt text needs no decoration as it will be descriptive.

styles

Figures are written with alt text in the square brackets, but no caption like so: ![alt text]({{ page.root }}/fig/image.png)

![a red baby dragon head sticks out from its egg]({{ page.root }}/fig/dragon-egg.png)

The dragon emerges!

one exception: github workflows are contained inside the .github/workflows folder↩︎
python in styles is required for validation and initialisation, but is not required for local rendering↩︎
R in styles is required for R Markdown-based lessons↩︎
caveat: we still need the GitHub actions, but those are buried in the .github folder↩︎