transition-guide.qmd

---
title: "Transition Guide: From Styles to Workbench"
format:
  html:
    css: transition-guide.css
---

## Background

The Carpentries Workbench is a replacement for the former [carpentries/styles]
lesson infrastructure. Lessons using The Carpentries Workbench have content
separated from styling and build tools for a more seamless experience in updates
to the lesson websites. In 2023, all lessons in official Carpentries lesson
programs will use The Workbench and will be converted using the
[lesson-transition tool](https://github.com/carpentries/lesson-transition#readme).

[carpentries/styles]: https://github.com/carpentries/styles

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


## For Maintainers

### Default Branch

:::::::::::::: {layout="[50, 50]"}
::: {.column .workbench}

#### Workbench

The default branch is always **`main`**

:::

::: {.column .styles}

#### styles

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

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

### Infrastructure

:::::::::::::: {layout="[50, 50]"}
::: {.column .workbench}

#### Workbench

The workbench infrastructure is **independent**^[one exception: github
workflows are contained inside the `.github/workflows` folder] from individual
lessons. It consists of three major pieces of software.

 - **Git **
 - **R**
 - **[Pandoc][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


:::

::: {.column .styles}

#### 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^[python in styles is required for validation and initialisation, but is not required for local rendering]
 - R^[R in styles is required for R Markdown-based lessons]


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

 - [bundler](https://bundler.io/): manages the Ruby gems (packages) including Jekyll
 - [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.

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

### Contributor Count

Because content and tools are separated in Workbench Lessons, giving credit for
the lesson is much more straightforward. Here we use Dr. Sarah Gibson's
[Cross-Stitch Carpentry
lesson](https://sgibson91.github.io/cross-stitch-carpentry/) as an example

:::::::::::::: {layout="[50, 50]"}


::: {.column .workbench}

#### Workbench

The Contributors reflect those that actually worked on the lesson itself.

![List of contributors reflects the lesson content contribution (note that Dr. Gibson is  listed first)](fig/contributors-workbench.png){alt='screenshot of github "contributors" short list showing 4 contributors with GitHub avatars.'}

:::

::: {.column .styles}

#### styles

The Contributors reflect those that worked on the lesson AND those that worked
on the underlying infrastructure, going back to 2013.

![List of contributors reflects lesson content and styles (note that Dr. Gibson is now fifth!)](fig/contributors-styles.png){alt='screenshot of github "contributors" short list showing 11 of 48 contributors with GitHub avatars.'}

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


### Local Rendering

:::::::::::::: {layout="[50, 50]"}
::: {.column .workbench}

#### Workbench

1. If you haven't already, Follow the [setup instructions for the workbench][workbench-setup] to install R, pandoc, and the workbench packages
2. In your lesson directory, open either [R](https://cloud.r-project.org/), [RStudio](https://www.rstudio.com/products/rstudio/download/#download), or [VS Code](https://code.visualstudio.com/docs/languages/r) and run:

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

:::

::: {.column .styles}

#### styles

1. If you haven't already, Follow the [setup instructions for styles](https://carpentries.github.io/lesson-example/setup) to install Ruby, Bundler, Jekyll, Make, Python, and BASH
2. In your lesson directory, open your command line and run:

```bash
make serve
```

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


### Folder Structure


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

 1. tools for building the lesson do not live in the lesson ^[caveat: we still need the GitHub actions, but those are buried in the `.github` folder]. 
 2. the episodes can be directly lifted from the lesson without needing external
    context/resources.
 3. 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/`.
![](fig/folder-flow.svg){data-alt='A diagram showing the transition between the
former lesson structure (styles) to the new lesson structure (workbench). It
shows episodes flowing to episodes, extras flowing to learners and instructors,
and figures, data, and files flowing to subfolders under episodes. Other
folders are in grey with no arrows indicating that they are discarded.'}


### Setup Page {#setup-maintainer}

::::::::::::::::::::::::::::::::::::::::::::::::::::::::: {.column-screen-inset}
:::::::::::::::::::::: {layout="[50,50]"}
::: {.column .workbench}

#### Workbench

The setup information lives in `learners/setup.md` or `learner/setup.Rmd`,
depending on whether or not you need code generated. Access this file from 
episodes with 

```markdown
[setup instructions](../learners/setup.md)
```

On the rendered site, the setup instructions are located on the home page at
the `#setup` anchor. 

:::

::: {.column .styles}

#### styles

The setup information lives in the top level of the lesson at `setup.md` (no
possibility to render generated content). Access this file from episodes with

```markdown
[setup instructions]({{ page.root }}/setup.md)
```

On the rendred site, the setup instructions are in a separate page called `/setup`

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



### Callout Blocks/Special Blockquotes {#callout-blocks}

::::::::::::::::::::::::::::::::::::::::::::::::::::::::: {.column-screen-inset}
:::::::::::::::::::::: {layout="[50,50]"}
::: {.column .workbench}

#### 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.

::::: {.callout-note}

You can find a demonstration of all the possible callout blocks in [the workbench component guide](https://carpentries.github.io/sandpaper-docs/component-guide.html)

:::::

```markdown
:::: callout

#### Act Openly

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

::::::::::::
```

::: {.callout-tip}

These are called [_fenced divs_][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.

:::
:::

::: {.column .styles}

#### 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


::::: {.callout-note}

You can find a demonstration of all the possible callout blocks in [the styles "Special Blockquotes" guide](https://carpentries.github.io/lesson-example/04-formatting/index.html#special-blockquotes)

:::::

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

::: {.callout-warning}

#### 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

::::::::::::::::::::::::::::::::::::::::::::::::::::::::: {.column-screen-inset}
:::::::::::::::::::::: {layout="[50,50]"}
::: {.column .workbench}

#### 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:
<br>
<br>

````markdown
clean all merged branches from git

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

:::

::: {.column .styles}

#### 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):

````markdown
clean all merged branches from git

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

### Challenge/Solution blocks

::::::::::::::::::::::::::::::::::::::::::::::::::::::::: {.column-screen-inset}
:::::::::::::::::::::: {layout="[50,50]"}
::: {.column .workbench}

#### 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.

````markdown
::::::::::::::::::::::::::::: 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()
```

::::::::::::::::::
:::::::::::::::::::::::::::::::::::::::
````

::: {.callout-tip}

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

:::


:::

::: {.column .styles}

#### 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" 

````markdown
> ## 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

::::::::::::::::::::::::::::::::::::::::::::::::::::::::: {.column-screen-inset}
:::::::::::::::::::::: {layout="[50,50]"}
::: {.column .workbench}

#### Workbench

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


````markdown
---
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][fenced-divs] at the _end_ of the document:

```markdown
...

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

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

:::::::::::::::::::::::::::
```

:::

::: {.column .styles}

#### styles

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

````markdown
---
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

...
````

::: {.callout-warning}

#### 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

::::::::::::::::::::::::::::::::::::::::::::::::::::::::: {.column-page}
:::::::::::::::::::::: {layout="[50,50]"}
::: {.column .workbench}

#### Workbench

An **inline instructor note** in the workbench is formed inside an episode by
making a [_fenced div_][fenced-divs] with the class "instructor"

```markdown
:::: instructor

Here be dragons

::::::::::::
```

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

:::

::: {.column .styles}

#### styles

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

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

### Lists

::::::::::::::::::::::::::::::::::::::::::::::::::::::::: {.column-page}
:::::::::::::::::::::: {layout="[50,50]"}
::: {.column .workbench}

#### Workbench

In general, if something does not work in Markdown, try adding a blank line.
This is true for lists.

A list must start and end with a blank line to be rendered properly:

::: {.panel-tabset}

##### Correct Syntax

```markdown
A list of things

- shoes
- coat
- glasses

text after the list
```

A list of things

- shoes
- coat
- glasses

text after the list


##### Incorrect Syntax

```markdown
A list of things
- shoes
- coat
- glasses

text after the list
```

A list of things
- shoes
- coat
- glasses

text after the list


##### Lists in fenced divs

Lists in fenced divs behave the same way and a common mode of failure is to
create a list inside a fenced div that does not have space around it:

```markdown
::: callout
- one
- two
- three
:::
```

This will result in a callout that has this content. Moreover, [the lesson build
will fail to validate](https://github.com/carpentries/sandpaper/issues/355):

- one
- two
- three
\:\:\:


Instead, please make sure you add blank lines around your list like this:

```markdown
::: callout

- one
- two
- three

:::
```


:::
:::

::: {.column .styles}

#### styles

Jekyll is very forgiving for lists in general, so a blank line before the list
is optional

```markdown
A list of things
- shoes
- coat
- glasses

text after the list
```

A list of things

- shoes
- coat
- glasses

text after the list
:::


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

### Tables

::: {.callout-note}

#### About Table Styling

Please note that the table display here is not a good representation of what
you will see in The Workbench or in Styles. They both have their own 
idiosyncratic ways of displaying tables. 

A demonstration of Workbench tables can be seen [in the official documentation
for lesson contributors](https://carpentries.github.io/sandpaper-docs/episodes.html#tables)

:::
::::::::::::::::::::::::::::::::::::::::::::::::::::::::: {.column-screen-inset}
:::::::::::::::::::::: {layout="[50,50]"}
::: {.column}
 .workbench

#### Workbench

Tables in the workbench follow the rules for [pandoc pipe table syntax](https://pandoc.org/MANUAL.html#extension-pipe_tables).

There are two extra features for this syntax in pandoc:

1. You can add a table caption, which is great for accessibility[^caption]
2. You have control over the relative width of oversized table contents

[^caption]: Captions allow visually impaired users to choose if they want to
  skip over the table contents if it is scannable. [MDN docs: adding a caption
  to your table](https://developer.mozilla.org/en-US/docs/Learn/HTML/Tables/Advanced#adding_a_caption_to_your_table_with_caption)

::: {.panel-tabset}

##### Short table with caption

```markdown
Table: A table of fruits and prices

| fruit  | price  |
| ------ | -----: |
| apple  | 2.05   |
| pear   | 1.37   |
| orange | 3.09   |
| devil  | 666.00 |
```

Table: A table of fruits and prices

| fruit  | price  |
| ------ | -----: |
| apple  | 2.05   |
| pear   | 1.37   |
| orange | 3.09   |
| devil  | 666.00 |


##### Wide table with caption

To control the width of columns in the table, adjust the number of `-` in the
separator between the header and the table body. This table has three columns
with a 2:1:1 ratio (as noted by the `|----|--|--|` header)

```markdown
Table: summary of relevant statistical tests for normally and non-normally distributed data

|Analysis required (continuous data) |Normally distributed data | Non-normally distributed data |
| ----                               | --                       | --                            |
|Compare mean or median of one sample group against a known value |One sample t-test |Wilcoxon Rank Sum test |
|Compare means or medians of two sample groups (unpaired data) |Unpaired t-test |Mann-Whitney test |
|Compare means or medians of two sample groups (paired data) |Paired t-test |Wilcoxon Matched Pairs test |
|Compare means or medians of ≥ three sample groups (unpaired data) |ANOVA |Kruskal-Wallis ANOVA |
|Compare means or medians of ≥ three sample groups (paired data) |Repeated measures ANOVA |Friedman test |

```

Table: summary of relevant statistical tests for normally and non-normally distributed data

|Analysis required (continuous data) |Normally distributed data | Non-normally distributed data |
| ----                               | --                       | --                            |
|Compare mean or median of one sample group against a known value |One sample t-test |Wilcoxon Rank Sum test |
|Compare means or medians of two sample groups (unpaired data) |Unpaired t-test |Mann-Whitney test |
|Compare means or medians of two sample groups (paired data) |Paired t-test |Wilcoxon Matched Pairs test |
|Compare means or medians of ≥ three sample groups (unpaired data) |ANOVA |Kruskal-Wallis ANOVA |
|Compare means or medians of ≥ three sample groups (paired data) |Repeated measures ANOVA |Friedman test |



```markdown
Table: table to demonstrate a wrapped cell

| with wrapping | without wrapping |
| --            | ------           |
| This is a lot of text for a very tiny cell. It almost certainly will be wrapped. | This is a lot of text for a wider cell. It will not wrap so soon. |
```

Table: table to demonstrate a wrapped cell

| with wrapping | without wrapping |
| --            | ------           |
| This is a lot of text for a very tiny cell. It almost certainly will be wrapped. | This is a lot of text for a wider cell. It will not wrap so soon. |

:::
:::

::: {.column .styles}

#### styles

[Jekyll tables](https://www.markdownguide.org/extended-syntax/#tables) are the same syntax, but with no ability to add captions or control width:

```markdown
| fruit  | price  |
| ------ | -----: |
| apple  | 2.05   | 
| pear   | 1.37   |
| orange | 3.09   |
| devil  | 666.00 |
```


| fruit  | price  |
| ------ | -----: |
| apple  | 2.05   | 
| pear   | 1.37   |
| orange | 3.09   |
| devil  | 666.00 |



:::


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

### Internal Links 

::::::::::::::::::::::::::::::::::::::::::::::::::::::::: {.column-screen-inset}
:::::::::::::::::::::: {layout="[50,50]"}
::: {.column .workbench}

#### 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.

```markdown
<!-- 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)
```

:::

::: {.column .styles}

#### 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:

```markdown
<!-- 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

::::::::::::::::::::::::::::::::::::::::::::::::::::::::: {.column-screen-inset}
:::::::::::::::::::::: {layout="[50,50]"}
::: {.column .workbench}

#### 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'}`.


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

::: {.callout-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.

:::


:::

::: {.column .styles}

#### styles

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

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

The dragon emerges!
```
:::

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

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



## For Instructors

### Navigation

::::::::::::::::::::::::::::::::::::::::::::::::::::::::: {.column-screen-inset}
:::::::::::::::::::::: {layout="[50,50]"}
::: {.column .workbench}

#### Workbench

Episode and setup information is located on the left hand side of the page.
Navigation in the workbench is split between information for learners and
information for instructors. The top right of the page has a toggle button
between Learner and Instructor views, which change the four main navigation
items in the top navigation bar. 


##### Learner View

When this is toggled, the main navigation contains the following menu items:
Key Points, Glossary, Learner Profiles, and More. The "More" dropdown menu
contains information for learners from the `learners/` folder aside from the
setup instructions.

![](fig/screenshot-learner-view.png){alt='screenshot of the workbench version
of "The Unix Shell". A blue arrow points to the top right corner indicating the
lesson is in "Learner View". The menu bar states the name of the lesson and has
the items described in text, with all but the first underlined. There is a grey
sidebar that says "Episodes" and a section called "Summary and Setup" is
underlined in blue. The main content shows a blue underline under the last
updated status.'}

##### Instructor view

When this is toggled, the main navigation contains the following menu items:
Key Points, Instructor Notes, Extract All Images, and More. The "More" dropdown
menu contains information for learners from the `instructors/` folder.

In addition, the schedule now appears on the home page, instructor notes are
displayed inline, and the estimated timings for a lesson appear.


![](fig/screenshot-instructor-view.png){alt='screenshot of the workbench
version of "The Unix Shell". A red arrow points to the top right corner
indicating the lesson is in "Learner View". The menu bar states the name of the
lesson and has the items described in text, with all but the first underlined
in red. There is a grey sidebar that says "Episodes" and a section called
"Summary and Setup" is underlined in red. The main content shows a red
underline under the last updated status.'}


:::

::: {.column .styles}

#### styles

Navigation in the styles repository is relegated to a single menubar at the top
of the lesson with seven items: Home, Code of Conduct, Setup, Episodes (dropdown),
Extras (dropdown), License, and Improve This Page. 


![](fig/screenshot-styles.png){alt='screenshot of the styles version
of "The Unix Shell" lesson highlighting a single navigation bar at the top
containing the items described in the text'}

::: {.callout-warning}

##### Perceived simplicity

While the styles repositories appear to be simpler, there were several components
of lessons (such as instructor notes and glossary terms) that were not clearly
available to learners or instructors. Moreover, in cases like instructor training,
where there was much extra content for both learners and instructors, it was not
easy to look at the "Extra" menu and determine what content was appropriate for
a learner or an instructor.

:::


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

### Setup Information {#setup-instructor}

::::::::::::::::::::::::::::::::::::::::::::::::::::::::: {.column-screen-inset}
:::::::::::::::::::::: {layout="[50,50]"}
::: {.column .workbench}

#### Workbench

The setup instructions are located on the home page at the `#setup` anchor. 

The link to get to the setup is located at the "Summary and Setup" (in
Learner View) or the "Summary and Schedule" links (in Instructor View) in the
side navigation bar:

![](fig/setup-workbench.png){alt='zoomed in screenshot of side navigation of
a workbench episode showing "Summary and Setup" highlighted'}

:::

::: {.column .styles}

#### styles

The setup instructions are in a separate page called `/setup`

The link for the setup instructions are located in the navigation bar.

![](fig/setup-styles.png){alt='screenshot of top navigation of styles with "setup" highlighted'}


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

### Improve/Edit This Page {#improve}

Our core values state that we value openness, all contributions, and are always
learning. This is why we have an "edit this page" button on all of our lessons,
so anyone can make suggestions. This button is always at the top and the bottom
of episodes.

::::::::::::::::::::::::::::::::::::::::::::::::::::::::: {.column-screen-inset}
:::::::::::::::::::::: {layout="[50,50]"}
::: {.column .workbench}

#### Workbench

The "Edit This Page" button is located under the heading for each episode:

![](fig/edit-page-head-workbench.png){alt='screenshot of workbench page header that says "Introduction to R" with a highlighted link that says "Edit this page"'}

and on the first column of the footer:

![](fig/edit-page-foot-workbench.png){alt='screenshot of workbench page footer that shows the "Edit on GitHub" link highlighted'}



:::

::: {.column .styles}

#### styles

The navigation bar in styles contains a link to "Improve this page":

![](fig/edit-page-head-styles.png){alt='screenshot of styles navigation bar with "Improve this page" highlighted'}

The footer contains a link to "Edit on GitHub"

![](fig/edit-page-foot-styles.png){alt='screenshot of styles footer with "Edit on GitHub" highlighted'}

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


### License {#license-instructor}

Our official lessons are all CC-BY, but lessons that are not official may have
alternative licenses. Moreover, code and data should also specify attribution
and reuse.

::::::::::::::::::::::::::::::::::::::::::::::::::::::::: {.column-screen-inset}
:::::::::::::::::::::: {layout="[50,50]"}
::: {.column .workbench}

#### Workbench

The License information can be found at the `LICENSE.html` page, whose link is
always in the footer:

![](fig/license-workbench.png){alt='screenshot of workbench footer with "CC-BY 4.0" license highlighted'}

:::

::: {.column .styles}

#### styles

The License information can be found at the `LICENSE.html` page, whose
link is in the header:

![](fig/license-styles.png){alt='screenshot of header with "License" highlighted'}

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

### Code of Conduct {#coc-instructor}

[The Carpentries Code of
Conduct](https://docs.carpentries.org/topic_folders/policies/code-of-conduct.html)
ensures that our workshops and lessons are a safe space to learn and create.
This link is always on our lesson pages. It provides rules for behaviour and
reporting guidelines.


::::::::::::::::::::::::::::::::::::::::::::::::::::::::: {.column-screen-inset}
:::::::::::::::::::::: {layout="[50,50]"}
::: {.column .workbench}

#### Workbench

The Code of Conduct information can be found at the `CODE_OF_CONDUCT.html` page, whose link is
always in the footer:

![](fig/coc-workbench.png){alt='screenshot of workbench footer with "Code of Conduct" highlighted'}

:::

::: {.column .styles}

#### styles

The Code of Conduct information can be found at the `CODE_OF_CONDUCT.html` page, whose link is in the header

![](fig/coc-styles.png){alt='screenshot of styles header with "Code of Conduct" highlighted'}


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

### All in One Page {#aio-instructor}

The all-in-one page concatenates all of the episodes in a lesson so that you can scroll through the episodes without having to switch pages. 

::::::::::::::::::::::::::::::::::::::::::::::::::::::::: {.column-screen-inset}
:::::::::::::::::::::: {layout="[50,50]"}
::: {.column .workbench}

#### Workbench

The link to this page is at `aio.html` and can be found at the bottom of the 
side navigation bar.

![](fig/aio-workbench.png){alt='screenshot of side navigation bar with episodes collapsed into an ellipsis, highlighting the "See all in one page" link'}


You can jump to individual episodes within this page by adding `#aio-[page
slug]` to the end of the URL.

For example, From the [Workbench
Documentation](https://carpentries.github.io/sandpaper-docs/), following
<https://carpentries.github.io/sandpaper-docs/aio.html#aio-episodes> will bring
you to the "Episode Structure" episode in the all in one page. 

:::

::: {.column .styles}

#### styles

The link to this page is at `aio.html` and can be found at the bottom of the 
episode dropdown in the navigation bar.

![](fig/aio-styles.png){alt='cropped screenshot of episodes dropdown navigation menu where "All in one page (beta)" has been highlighted'}

Note that there is no clear division between the episodes in this page.

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

[kramdown]: https://kramdown.gettalong.org/syntax.html
[pandoc]: https://pandoc.org/MANUAL.html#pandocs-markdown
[jekyll]: http://jekyllrb.com/
[fenced-divs]: https://pandoc.org/MANUAL.html#divs-and-spans
[{varnish}]: https://carpentries.github.io/varnish/
[{pegboard}]: https://carpentries.github.io/pegboard/
[{sandpaper}]: https://carpentries.github.io/sandpaper/
[{tinkr}]: https://docs.ropensci.org/tinkr/
[workbench-setup]: https://carpentries.github.io/sandpaper-docs/#setup