Style Guide

Overview

Teaching: 10 min
Exercises: 0 min
Questions
  • What style should be used for Carpentries lessons?

  • How are keyboard key combinations written?

  • How are short spans of code written?

Objectives
  • Explain keyboard key combination.

  • Locate documentation for general matters of style in The Carpentries.

  • Identify uses of the span of code Markdown feature.

This episode contains lesson-specifc style guidance and related implementation details related to The Carpentries lesson template. For more general matters of style, see the The Carpentries Style Guide.

Emphasis

Markdown treats asterisks (*) indicators of emphasis, and renders text marked up like this in italics. We use emphasis

Strong Emphasis

Markdown treats double asterisks (**) as indicators of strong emphasis, and renders text marked up like this in boldface. We use strong emphasis

Span of Code

Markdown treats backtick quotes (`) as indicators of a span of code. We use span of code

Keyboard Key

When making reference to a keyboard key that the reader should press the HTML tag <kbd> must be used to enclose the key label. For example, “to delete the cell press D” should be write as

to delete the cell press <kbd>D</kbd>

The table below covers most of the keyboard key labels.

Keyboard key Style Note Example
Letters Always capital. <kbd>A</kbd>
Numbers   <kbd>1</kbd>
Punctuation mark   <kbd>*</kbd>
Function Capital F followed by the number. <kbd>F12</kbd>
Alt Only first letter capital. <kbd>Alt</kbd>
Backspace Only first letter capital. <kbd>Backspace</kbd>
Command Only first letter capital. <kbd>Command</kbd>
Ctrl Only first letter capital. <kbd>Ctrl</kbd>
Delete Only first letter capital. <kbd>Delete</kbd>
End Only first letter capital. <kbd>End</kbd>
Esc Only first letter capital. <kbd>Esc</kbd>
Home Only first letter capital. <kbd>Home</kbd>
Insert Only first letter capital. <kbd>Insert</kbd>
Page Down Use “PgDn”. <kbd>PgDn</kbd>
Page Up Use “PgUp”. <kbd>PgUp</kbd>
Print Screen Use “PrtScr”. <kbd>PrtScr</kbd>
Return Only first letter capital. We use “Return” instead of “Enter”. <kbd>Return</kbd>
Shift Only first letter capital. <kbd>Shift</kbd>
Spacebar Only first letter capital. <kbd>Spacebar</kbd>
Tab Only first letter capital. <kbd>Tab</kbd>
Down arrow Use Unicode “Downwards arrow” (8595). <kbd>↓</kbd>
Left arrow Use Unicode “Leftwards arrow” (8592). <kbd>←</kbd>
Right arrow Use Unicode “Rightwards arrow” (8594). <kbd>→</kbd>
Up arrow Use Unicode “Upwards arrow” (8593). <kbd>↑</kbd>

Keyboard Key Combination

When making reference to a keyboard key combination that the reader should press, insert a plus sign without space between each one of the keys. For example, “press Ctrl+X to quit nano” should be written as:

press <kbd>Ctrl</kbd>+<kbd>X</kbd> to quit nano.

Please label links with meaningful texts, in order to improve accessibility. Please avoid click here or similar.

Use double quotes for menu and submenu items. For multiple menu and submenu options in a sequence, use the right angle bracket or greater than sign.

e.g.:

“Help” > “Check for updates”

Title Casing

Lesson and episode titles should be written in title case e.g.

Saving the World, One Commit at a Time

An exception should be made where the title includes the name of a tool/library/command that must be typed in lower case when used, e.g.

Data Visualisation with matplotlib

(In HTML files, such as the workshop schedule and syllabus files in the workshop webpage template, tool/command/library names such as matplotlib in the example above can be correctly formatted using <code></code> tags.)

Key Points

  • The Carpentries Handbook contains a style guide.

  • Keyboard actions are described using the <kbd> HTML tag.

  • A backtick (`) indicates a span of code and is used to enclose code excerpts, segments of text to type, and filenames within in narrative text.