General tutorial text style guide¶
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.
All tutorials are written with Markdown syntax. Each page should have a title (
#) and sub-sections (
###). 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 (
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:
|row 1 thing||row 1 thing||row 1 thing|
|row 2 thing||row 2 thing||row 2 thing|
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¶
|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¶
|Conda environment names||
|File names and paths||
*Use the backticks for folders and file names in relative or absolute paths. Use " " for the folder or file name itself
> for quoted text.
> This is a quote!
This is a quote!
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:
|Usage||to demo code command syntax||
|Input||to demo actual code users should type||
|Output||to demo the expected output results||
=== "Input" ``` samtools --version ``` === "Expected Output" ``` samtools 1.10 Using htslib 1.10.2 Copyright (C) 2019 Genome Research Ltd. ```
This renders as:
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
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'.
|other pages in the Github repo||
|URLs with title||
|URL link itself||
*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">
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
latestbranch of the Github repo. You don't need to worry about this - it'll be solved when PR changes are merged.
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
!!! note Lesson notes, learning objectives, prerequisites (see below)
Lesson notes, learning objectives, prerequisites (see below)
!!! warning Warnings (e.g., actions that result in data loss or incur costs to run)
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)
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 for the lesson
!!! note "Key Points" Lesson key points/take home messages
Lesson key points/take home messages
Admonition blocks do not render on Github. More examples are shown on the supported types page.