Style guide

This page provides guidelines for writing PennController documentation.

---

General

This website recommends following the Google developer documentation style guide when writing documentation, in particular its rules for tone and grammar.

Tone

• Be conversational and friendly without being frivolous.
• Write with reading ease in mind.
• Use descriptive link text.

Grammar

• Use active voice and present tense.
• Put conditional clauses before instructions, not after.
• Use second person when giving instructions.

---

Markdown syntax conventions

This website uses Markdown. If you’re new to Markdown, read this Getting Started overview and Basic Syntax guide before continuing.

There is some variation in Markdown syntax; for consistency across this website, please follow these conventions in your Markdown files.

Headings

Use pound signs (#) to create headings:

input

      
# Heading level 1 (h1)
## Heading level 2 (h2)
### Heading level 3 (h3)
#### Heading level 4 (h4)
##### Heading level 5 (h5)
###### Heading level 6 (h6)

    

Italic text

Use a single asterisk * for italicized text:

input

      
This sentence has *italicized* text.

    

output

This sentence has italicized text.

Bold text

Use double asterisks ** for bold text:

input

      
This sentence has **bold** text.

    

output

This sentence has bold text.

Ordered list

To create an ordered list, add a number followed by a period in front of each list item:

input

      
1. Lorem
2. Ipsum
3. Dolor

    

output

1. Lorem
2. Ipsum
3. Dolor

Unordered list

To create an unordered list, add a plus sign + in front of each list item:

input

      
+ Lorem
+ Ipsum
+ Dolor

    

output

• Lorem
• Ipsum
• Dolor

---

Horizontal rule

Create a horizontal rule with three dashes ---:

input

      
This is text above a horizontal rule.

---

This is text below a horizontal rule.

    

output

This is text above a horizontal rule.

---

This is text below a horizontal rule.

Internal links

Internal links should be in the form [LINK_TEXT]({{site.baseurl}}/PAGE_PATH). Do not hardcode the website url, as in [LINK_TEXT](https://doc.pcibex.net/PAGE_PATH).

input

      
  
  This is a link to the [Core Concepts]({{site.baseurl}}/core-concepts) section.


    

output

This is a link to the Core Concepts section.

A page’s page path is likely different from its file path. For example, the file path for the standard.after command is reference/_standard-element-commands/standard-after.md, but its page path is /standard-element-commands/standard-after.

If you are not sure what a page’s page path is, open that page and check its URL in the address bar of your web browser.

External links

External links should open in a new tab: add {:target="_blank"} after the URL.

input

      
This is a link to the
[`penncontroller.github.io`](https://github.com/PennController/penncontroller.github.io){:target="_blank"}
repository.

    

output

This is a link to the penncontroller.github.io repository.

Blockquotes

If you want to draw emphasis to a certain section, create a note instead of using a blockquote:

input

      
  
  {% capture label %}
  This is an example note. Notes support Markdown syntax, meaning that you can
  freely *italicize* and **bold** text, and even create lists:

  1. Lorem
  2. Ipsum
  3. Dolor

  + Consectetur
  + Adipsicing
  + Elit
  {% endcapture %}
  {% include label-note.html label-body=label %}
  

    

output

note

This is an example note. Notes support Markdown syntax, meaning that you can freely italicize and bold text, and even create lists:

1. Lorem
2. Ipsum
3. Dolor

• Consectetur
• Adipsicing
• Elit

Inline code

In general, use backticks ` for inline code:

input

      
This is a sentence with `inline code`.

    

output

This is a sentence with inline code.

If you want to include italicized text in inline code to indicate a placeholder variable, use <code><var>PLACEHOLDER_VARIABLE</var></code>

input

      
  This is a sentence with an <code>inline code <var>variable</var></code>.

    

output

This is a sentence with an inline code variable.

---

Markdown code blocks

The PennController website uses the Prism syntax highlighter to style code blocks, instead of the default Rouge highlighter. Since PennController is based on JavaScript, use JavaScript as the language for syntax highlighting.

There are two types of code blocks: without line highlighting, and with line highlighting.

Code blocks without line highlighting

If you’re creating a code block without line highlighting, create a fenced code block by surrounding the code with ```javascript and ```:

input

      
```javascript
// This is a comment

PennController.ResetPrefix(null)

newTrial("example-trial",
    newText("hello", "Hello World!")
        .print()
    ,
    newButton("wait", "")
        .wait()
)
```

    

Code blocks with line highlighting

If you’re creating a code block with line highlighting, surround the code with <pre><code class="language-diff-javascript diff-highlight"> and </code></pre>.

Every line in the code block should begin with one of the following symbols:

• $: Purple line highlight; used to place general emphasis on a line.
• +: Green line highlight with a plus sign; used to indicate an added line.
• -: Red line highlight with a minus sign; used to indicate a deleted line.
• !: Yellow line highlight with an exclamation mark; used to indicate a changed line.
• ~ Green line highlight; used to indicate correctness.
• %: Red line highlight; used to indicate incorrectness.
• @: Default syntax highlighting.

If the @ symbol is omitted, that line does not receive any syntax highlighting. The @ symbol is not striclty required for empty lines, as there is no code to be highlighted, but you should include it anyways for consistency.

The start symbol is added in addition to any indenting spaces. For example, if a line is indented by four spaces, that line should begin with a start symbol and four spaces, for a total of five characters before the code on that line begins.

input

      
<pre><code class="language-diff-javascript diff-highlight">
$PennController.ResetPrefix(null)
@
+newTrial("example-trial-one",
+    newText("hello", "Hello World!")
-        .print()
-    ,
!    newButton("wait", "")
!        .wait()
$)
@
@// CORRECT: The 'newX()' function is called inside a trial
~newTrial("trial-with-element",
~    newX("element-inside-trial")
~)
@
@// INCORRECT: The 'newX()' function is called outside of a trial
%newX("element-outside-trial")
%newTrial("trial-without-element")
@
@// This is a comment with syntax highlighting
// This is a comment without syntax highlighting
@
@PennController.ResetPrefix("apple")    // Code with syntax highlighting
PennController.ResetPrefix("apple")    // Code without syntax highlighting
</code></pre>

    

output

$PennController.ResetPrefix(null)
@
+newTrial("example-trial-one",
+    newText("hello", "Hello World!")
-        .print()
-    ,
!    newButton("wait", "")
!        .wait()
$)
@
@// CORRECT: The 'newX()' function is called inside a trial
~newTrial("trial-with-element",
~    newX("element-inside-trial")
~)
@
@// INCORRECT: The 'newX()' function is called outside of a trial
%newX("element-outside-trial")
%newTrial("trial-without-element")
@
@// This is a comment with syntax highlighting
// This is a comment without syntax highlighting
@
@PennController.ResetPrefix("apple")    // Code with syntax highlighting
PennController.ResetPrefix("apple")    // Code without syntax highlighting

---

Markdown style rules

The following style suggestions are based on the rules from the Visual Studio Code extension markdownlint. For a full list of its rules, see Rules.

Headings

Surround headings with blank lines (one blank line above and one blank line below the heading)

input

      
CORRECT:

## Heading 2

Lorem ipsum dolor sit amet, consectetur adipiscing elit.

## Heading 2

Lorem ipsum dolor sit amet, consectetur adipiscing elit.

INCORRECT:

## Heading 2
Lorem ipsum dolor sit amet, consectetur adipiscing elit.

Lorem ipsum dolor sit amet, consectetur adipiscing elit.
## Heading 2

    

Whitespace

• Use spaces instead of hard tabs for indentation.
• Avoid trailing spaces at the end of a line.
• Avoid multiple consecutive blank lines.

Line length

Wrap lines that are longer than 80 characters long for readability.

However, links are frequently close to over 80 characters, but must be on a single line in order to be parsed properly. In such cases, place the link on its own line.

input

      
CORRECT: The link is on its own line, for a total of three lines.

This is a link to the
[`penncontroller.github.io`](https://github.com/PennController/penncontroller.github.io){:target="_blank"}
repository.

INCORRECT: The link is on the same line, for a total of one line. However, the
example looks like two lines because of word wrapping within the code block.

This is a link to the [`penncontroller.github.io`](https://github.com/PennController/penncontroller.github.io){:target="_blank"} repository.

    

---

YAML tags

• If the value contains a colon, surround the value with single or double quote to escape the special colon character:

    ---
    example: "This sentence contains a colon : and needs quotes"
    ---
  

• If the value contains double quotes, surround the value with single quotes to escape the double quotes:

    ---
    example: '"first"'
    ---
  

• To be filled in