Standards for technical references in [#technical-documentation]

This technical references guide outlines when and how to use code samples in written content.

Code and Code Blocks

To denote a word or phrase as code, enclose it in backticks. For example, `cp * folder/`.

Format the following technical references as code:

  • Command line interface (CLI) entries:

    cd Desktop/

  • Scripts:

    npm run dev

  • Single lines of code:

    console.log('Print this message to the console')

For multi-line code samples, wrap the code in a fenced code block enclosed in three opening and closing backticks as shown in the example below:

```javascript
function printName () {
    let name = prompt("Please enter your name")
    alert(`Your name is ${name}`)
}
```

The above code block renders as:

function printName () {
    let name = prompt("Please enter your name")
    alert(`Your name is ${name}`)
}

Apply syntax highlighting to a multi-line code block by placing a language identifier next to the opening backticks of such a code block. Language identifiers must be written in lowercase. For example, the above code block’s identifier is labeled javascript, which applies JavaScript syntax highlighting.

To display triple backticks within a code block, wrap the entire code block in four opening and closing backticks.

Filenames or directory paths

When referenced, file names or directory paths should be emphasized and bold. You can achieve this by wrapping the file or directory with three starting and three ending asterisks.

For example:

  • The name of the current file is:

    technical-references-standards.md

  • Which appears in the Markdown like this:

    ***technical-references-standards***

  • The file can be found in the directory:

    src/pages/topics/technical-documentation/

  • Which appears in the Markdown like this:

    ***src/pages/topics/technical-documentation/***

However, you do not need to bold and emphasize filenames or directories when they are part of codes or code blocks.

Example of a directory within a code:

  • const example Url = '/src/styles/example-stylesheet.css'

Example of a directory within a code block:

```css
.element-class:before {
  background-image: url('../img/example-image.svg')
}
```

Graphical user interface elements

When describing graphical user interface (GUI) elements like menu selections and buttons, use bold and proper case formatting. Use a “greater than” symbol (>) between multiple menu selections.

For example:

  • File > View > Command Palette

Like the example above, always bold UI elements or menu selections.

Keyboard commands

Wrap keys in <kbd></kbd> tags. For example:

Press Ctrl+v to copy the selected text to the clipboard.

About Technical Documentation
  • Name: Technical Documentation (#technical-documentation)