Style Guide
Last updated on 2025-07-25 | Edit this page
A collection of guidelines to follow when writing source (R) Markdown files for use with {sandpaper}. The Carpentries also provides a general Style Guide for written content e.g. blog posts, website and lesson content, etc.
Fenced Divs
Fence Length
The following recommendations are made to improve legibility and make it easier to distinguish between blocks of content in source files.
First-level fenced divs
For increased legibility, we recommend an opening fence length of around 50 characters (half to two-thirds of the screen), with a single space between the last colon and the class keyword. The length of closing fences should match the length of the opening fence plus keyword, for example:
Nested fenced divs (e.g. challenge solutions)
Where fenced divs are nested, e.g. attaching a solution block to a challenge, we recommend making the inner fences noticably shorter than the outer fences, e.g. 25 characters (one quarter to one third of the screen). E.g.
MARKDOWN
:::::::::::::::::::::::::::::::::::::::: challenge
### An example challenge
This challenge was opened with a fence of 50 characters.
:::::::::::::::: solution
The nested solution block was opened with 25 characters,
to make it stand out from the challenge.
:::::::::::::::::::::::::
::::::::::::::::::::::::::::::::::::::::::::::::::Whitespace
For legibility and to avoid potential formatting issues, empty lines should flank the fences of a fenced div, e.g.
MARKDOWN
:::::::::::::::::::::::::::::::::::::::::: callout
### Good: whitespace either side of the fences
This will ensure Markdown content renders as intended.
::::::::::::::::::::::::::::::::::::::::::::::::::
:::::::::::::::::::::::::::::::::::::::::: callout
### Not recommended
Without empty lines flanking the opening and closing fences,
this callout is more difficult to read
and some Markdown content such as lists may not render as intended.
::::::::::::::::::::::::::::::::::::::::::::::::::Figures
We recommend splitting Markdown image elements across multiple lines, to enhance readability:
MARKDOWN
.
](path/to/figure.svg){
alt='Alternative text descriptions are defined here'
width='33%'
}Source Markdown for figures can be difficult to read when confined to a single line, especially if the image caption contains its own Markdown elements such as links.
For comparison, here is the one-line equivalent to the example above:
Line Length
We recommend writing one complete sentence per line in source (R) Markdown files. Although this can result in some long lines, keeping complete sentences in a single line makes it easier to internationalise lessons via machine-assisted translation.
Most text editors can be configured to display long lines “wrapped” to the width of the screen, or to a maximum length specified by the user. This is sometimes referred to as “word wrap”, “soft wrap”, or “visual wrap”, and can aid readability when working on lessons in your local environment. Below are links to guidance for activating line wrapping in several popular text editors/integrated development environments:
A note about line breaks
In Markdown, two spaces at the end of a line is interpreted as a line
break (i.e. converted to <br/> in the output HTML).
When ending a sentence in your source files, make sure to avoid leaving
two spaces at the end of the line unless you want a line break to appear
after it in your HTML output. See the example below.
MARKDOWN
This sentence is followed by two space characters in the source Markdown.
But this sentence is not.
Look where this sentence appears in the rendered output below.This sentence is followed by two space characters in the source
Markdown.
But this sentence is not. Look where this sentence appears in the
rendered output below.