Skip to content

General tutorial text style guide

Accessibility

Please ensure that our tutorials are accessible to the blind or visually impaired by:

  • writing descriptive text for hyperlinks. Avoid using "Click here".

  • writing descriptive text for images that screenreaders can detect. If you want to check how images look, use a color blindness simulator, such as toptal

  • when possible, avoiding color combinations or images that are not color-blind friendly. If you are creating figures in R, there is a colorblind friendly palette.

More details on accessible formats below.

Headers

All tutorials are written with Markdown syntax. Each page should have a title (#) and sub-sections (## or ###). The sub-sections cannot use #, otherwise the right-side TOC will not render. The syntax must have a space between the # and the text to render as a header:

# Title

## Introduction

### Resources

Markdown syntax allows up to 6 levels of hierarchy, however, if you need headings beyond level 3, this is a good indication that the tutorial page could benefit from being broken down into separate pages. Please try to only use level 2 (##) and 3 (###) headings.

Markdown tables

Tables columns are defined with | and rows with -. Markdown cell widths are set to be the same for each column when rendered by Mkdocs. The syntax looks like this:

col1 | col2 | col 3
--- | --- | ---
row 1 thing | row 1 thing | row 1 thing
row 2 thing | row 2 thing | row 2 thing

When rendered, the table looks like this:

col1 col2 col 3
row 1 thing row 1 thing row 1 thing
row 2 thing row 2 thing row 2 thing

Differentiating text

Use Markdown formatting to differenciate blocks of text, code, quotes, and hyperlinks. Several format guidelines are inspired from DigitalOcean's technical writing guide.

In-line text formatting with quotation marks

Use Example
Buttons to click "Launch", "Download"
Text on webpages look for the "Actions" column
File names A text file called "download-links.txt" *
Folder names create a folder called "KF_Data"

*If you refer to this specific file many times, you can put the file name in quotations for the first mention. The "Snakefile" in the Snakemake tutorial is an example where we state that the file is called "Snakefile" but thereafter simply refer to it as Snakefile.

In-line code formatting with single backticks

Use Example
Command names nano
Package names plink
Optional commands git branch -d
Conda environment names base
File names and paths ./docs/images/ *
File extensions .fastq.gz
Ports :3000
Github branches stable

*Use the backticks for folders and file names in relative or absolute paths. Use " " for the folder or file name itself

Quotes

Use > for quoted text.

> This is a quote!

renders as:

This is a quote!

Code blocks

Use triple backticks for lines of code that users need to execute to do the tutorial, example code syntax, and command-line terminal outputs.

The triple backtick format auto-generates a copy/paste feature in the top right corner of the gray text box. Do not include the command prompt symbol $ in the command, as it will result in a syntax error if users copy/paste the command with the $.

Divide multiple lines of code into separate blocks (unless they can be executed all together if copy/pasted) or indicate that commands must be run one at a time. For multi-line code blocks, include a short description of what the command does using the # to comment within the code block, e.g.,:

# change directories
cd ~/Desktop/test

# make a new file
nano newfile.txt

For showing input and output code:

Code block About Example
Usage to demo code command syntax echo <text>
Input to demo actual code users should type echo 'hello world'
Output to demo the expected output results hello world! in a javascript tabbed box format

Use javascript user-chooseable tabs to differentiate between input/expected output code or exercise/answer with the following syntax:

=== "Input"

    ```
    samtools --version
    ```

=== "Expected Output"

    ```
    samtools 1.10
    Using htslib 1.10.2
    Copyright (C) 2019 Genome Research Ltd.
    ```

This renders as:

samtools --version
samtools 1.10
Using htslib 1.10.2
Copyright (C) 2019 Genome Research Ltd.

Use this structure for exercises:

=== "Exercise"

    Exercise question

=== "Answer"

    ```
    code answer
    ```
    You can also add regular text or images

For some tutorials, you may want to distinguish between code entered at the terminal vs. code entered in a text editor. The Snakemake rules are an example of this distinction, where Snakemake rule code is added to a file and not entered at the terminal:

=== "Snakemake rule"

    Backticks and indentation important for rendering the entire rule in a code block

    ```
    rule rule_name:

    shell:

        # for single line commands

        # command must be enclosed in quotes

        "command"
    ```

We are also using this tabbed format for "Prerequisites" and "Tutorial Resources". This format helps to declutter the front matter so there are fewer admonition boxes:

=== "Prerequisites"

    Specify tutorial prerequisites (e.g., experience level, OS system, software installations)

=== "Tutorial Resources"

    e.g., cheat sheets, example scripts

Keys syntax

Syntax for keyboard keys will follow the Keys PyMdown extension format. It is built around the + symbol. A single of combination of keys is surrounded by ++ while each key is separated by a single +. List of all available key syntax are listed on the official Keys extension page.

Example syntax for CTRL+C would be Ctrl+C which will render as keyboard keys in the site.

Use hyperlinks to link images, other Markdown files, or websites. Provide short but descriptive text for the links instead of 'Click here' or 'Click this'.

Type Syntax
images ![](relative/path/to/docs/images/imagefile "short description of image") *
tutorial references [text about the reference](relative/path/to/docs/Resources/referencefile)
other pages in the Github repo [text about the page](relative/path/to/page/in/Github/repo/filename)
URLs with title [text about the website](URL)
URL link itself <URL>

*By including a short description of the image in the quotations marks, screen readers can provide information about the image without needing to see the image. This is one way to make images accessible to the blind or vision-impaired.

Note that the image link format below results in a broken image link on Mkdocs, even though it renders on Github Markdown:

<img src="path/to/img" title="short description of image" width="200" height="300">

The htmlproofer plugin checks for broken page and URL links when a pull request (PR) is submitted to the Github repo. The results are shown in the Checks tab of the PR page. Under Build documentation on PR and under build-and-deploy, expand the Build site section to view any error messages. Common issues:

  • WARNING: for links on pages that are broken, file paths that don't exist anymore because of file name changes
  • 404 error: page does not exist. This might be because it is a brand new file or the file was changed and neither are on the latest branch of the Github repo. You don't need to worry about this - it'll be solved when PR changes are merged.

Admonition types

There are several built-in admonition styles, and it is possible to add custom titles and styles. Below is the syntax for commonly used built-in styles to highlight important information:

!!! tip

    Lesson tips/shortcuts/alternatives

Tip

Lesson tips/shortcuts/alternatives

!!! note

    Lesson notes, learning objectives, prerequisites (see below)

Note

Lesson notes, learning objectives, prerequisites (see below)

!!! warning

    Warnings (e.g., actions that result in data loss or incur costs to run)

Warning

Warnings (e.g., actions that result in data loss or incur costs to run)

!!! error

    Errors users may encounter and what to do about them (e.g., software installation errors)

Error

Errors users may encounter and what to do about them (e.g., software installation errors)

Customize admonition titles by specifying the admonition title in quotes. For example:

!!! note "Learning Objectives"

    Learning objectives for the lesson

Learning Objectives

Learning objectives for the lesson

!!! note "Key Points"

    Lesson key points/take home messages

Key Points

Lesson key points/take home messages

Admonition blocks do not render on Github. More examples are shown on the supported types page.


Last update: December 8, 2020