Style Guide

Formatting rules and guidelines for Pantheon's open-source documentation.

Contributors: Alex Fornuto, Rachel Whitton.

Tweet

All documentation repositories should adhere to a style guide. This document serves to define and detail the style conventions used in Pantheon's Documentation.

You can also reference the Pantheon Documentation Template to see the common structure of our docs, or copy it to begin a new content piece.

Content Types

The site features two distinct content types; docs and guides. We define docs as reference materials used to explain the behavior and intended use of Pantheon's platform features and service offerings. Guides are generally paginated and designed to walk the reader through a specific concept or task.

Voice, Style, and Flow

Some General Rules:

  • Avoid be verbs.
  • Avoid colloquialisms and personal opinions, feelings, or anecdotes. Use an informal but succinct tone.
  • Only assume as much knowledge from the reader as specified in the Before You Begin section. Otherwise explain everything.

Frontmatter

Meta data for a doc or guide is created in a section referred to as frontmatter. It lives at the very top of the file and is wrapped in three dashes.

Style Guide

Formatting rules and guidelines for Pantheon's open-source documentation.

Contributors: Alex Fornuto,  Rachel Whitton



---
title: Style Guide
description: Formatting rules and guidelines for Pantheon's open-source documentation.
contributors: [alexfornuto, rachelwhitton]
---

Before You Begin

This section should outline any steps or services required before starting those in the doc. If there are other docs that should be completed first, list them here.

Of particular note, any documentation that uses Terminus should reference it in this section, and link to the Terminus Manual.

Before You Begin

Be sure that you have:



## Before You Begin

Be sure that you have:

- An existing WordPress site on Pantheon, or [create](https://dashboard.pantheon.io/sites/create) one.
- A [local clone](/git/#clone-your-site-codebase) of your code repository.
- An account with [Amazon Web Services (AWS)](https://aws.amazon.com/s3/). Amazon offers [free access](https://aws.amazon.com/free/) to most of their services for the first year.
- [Terminus](/terminus) installed on your local computer.

Export Local Environment Variables

Be kind. If you're writing a guide that will use one or more example variables the reader must replace when following along, you should walk them through exporting them to local environment variables. See the Variables section below for more details.

Typography

Headings

Page Title

Header

Sub Header

Section not listed on TOC



---
title: Page Title
---

## Header

### Sub Header
#### Section not listed on TOC

Bold

Bold is used for navigational elements within a given interface:

Go to Account > Security > Personal Access Tokens.



Go to **Account** > **Security** > **Personal Access Tokens**.

Bold is also used when defining new terms, in cases where the Definition List doesn't fit:

Transport Layer Security (TLS) refers to a set of cryptographic security protocols used to encrypt network traffic.



**Transport Layer Security** (TLS) refers to a set of cryptographic security protocols used to encrypt network traffic.

Italics

Emphasis should always be stressed with italics, and never with bold.



Emphasis should *always* be stressed with italics, and *never* with bold.

Definition List

Term
Definition.
Another Term
Description of the new term.


<dl>

<dt>Term</dt>

<dd>Definition.</dd>

<dt>Another Term</dt>

<dd>Description of the new term.</dd>

</dl>

Do not specify a target tab or window for external, or any other links, leaving the viewer the option to open in a new tab.

Use relative paths when linking to other pages of the docs site.

Quick Start



[Quick Start](/guides/quickstart)

Wikipedia entry on Style guide



[Wikipedia entry on Style guide](https://en.wikipedia.org/wiki/Style_guide)

Code

Inline

Used for file names, variables, commands, and output, inline within paragraphs:

Inline code styling using backticks, like $EXAMPLE.



Inline code styling using backticks, like `$EXAMPLE`.

Blocks

/**
* Example Comment
*
* To provide additional context for the following
* code, and defining any variables the user must
* manually edit.
**/
if (!function_exists('install_drupal')) {
  $conf['preprocess_css'] = 1;
}


```php
# This is a Windows-friendly symlink
require_once WP_CONTENT_DIR . '/plugins/wp-redis/object-cache.php';
```

Shell Prompts

You can also define a single line code block as a command:

mkdir -p ~/repos/mdx-slug


```bash{promptUser: user}
mkdir -p ~/repos/mdx-slug
```

Or define which lines are output:

ls  -1 ~/repos
documentation
i3lock-color
i3lock-fancy
j4-dmenu-desktop
mdx-slug


```bash{outputLines:2-6}
ls  -1 ~/repos
documentation
i3lock-color
i3lock-fancy
j4-dmenu-desktop
mdx-slug
```

Line Highlighting

You can highlight a specific line in a code block the reader should focus on with //highlight-line, or a group with //highlight-start and //highlight-end:

curl -I dev.mysite.com
HTTP/1.1 200 OK
X-Pantheon-Styx-Hostname: styx1a
server: nginx/1.0.15
content-type: text/html; charset=utf-8
x-drupal-cache: MISS
set-cookie: SESSf60876d132c0913e5fc728eec7f71e38=M1Sr0bxLbbgYmbg1EW7N8sGF4anrKP1np25EkYta-ZU; expires=Wed, 19-Dec-2012 22:04:58 GMT; path=/; domain=.dev.mysite.com; HttpOnlyCache-Control: no-cache, must-revalidate, max-age=0last-modified: Mon, 26 Nov 2012 18:31:30 +0000
expires: Sun, 19 Nov 1978 05:00:00 GMT
x-pantheon-endpoint: c18646dd-aa2b-4faa-a4e3-d71ec3a5ce43
Date: Mon, 26 Nov 2012 18:31:38 GMT
X-Varnish: 486741958
Age: 0Via: 1.1 varnish
Connection: keep-alive
X-Pantheon-Edge-Server: 108.166.58.245
Vary: Accept-Encoding, Cookie


```bash{outputLines: 2-20}
curl -I dev.mysite.com
HTTP/1.1 200 OK
X-Pantheon-Styx-Hostname: styx1a
server: nginx/1.0.15
content-type: text/html; charset=utf-8
x-drupal-cache: MISS
//highlight-start
set-cookie: SESSf60876d132c0913e5fc728eec7f71e38=M1Sr0bxLbbgYmbg1EW7N8sGF4anrKP1np25EkYta-ZU; expires=Wed, 19-Dec-2012 22:04:58 GMT; path=/; domain=.dev.mysite.com; HttpOnly
Cache-Control: no-cache, must-revalidate, max-age=0
//highlight-end
last-modified: Mon, 26 Nov 2012 18:31:30 +0000
expires: Sun, 19 Nov 1978 05:00:00 GMT
x-pantheon-endpoint: c18646dd-aa2b-4faa-a4e3-d71ec3a5ce43
Date: Mon, 26 Nov 2012 18:31:38 GMT
X-Varnish: 486741958
Age: 0 //highlight-line
Via: 1.1 varnish
Connection: keep-alive
X-Pantheon-Edge-Server: 108.166.58.245
Vary: Accept-Encoding, Cookie
```

File Excerpts

File excerpts are code blocks with a file name specified after the syntax as :title=FILENAME:

.gitignore
# WordPress #
############
wp-config-local.php
wp-cli.local.yml
wp-content/uploads
wp-content/blogs.dir/
wp-content/upgrade/


```git:title=.gitignore
# WordPress #
############
wp-config-local.php
wp-cli.local.yml
wp-content/uploads
wp-content/blogs.dir/
wp-content/upgrade/
```

Variables

When writing multi-step processes, repeated variables and constants should be defined before providing the first set of commands. If the doc has a "Before You Begin" section, define varables here. Provide them using the callout below, and follow common conventions (lowercase for variables, uppercase for constants).

 Exports

This process uses Terminus extensively. Before we begin, set the variables $site and $env in your terminal session to match your site name and the Dev environment:

export site=yoursitename
export env=dev


<Alert title="Exports" type="export">

This process uses [Terminus](/terminus) extensively. Before we begin, set the variables `$site` and `$env` in your terminal session to match your site name and the Dev environment:

```bash
export site=yoursitename
export env=dev
```

</Alert>

Callouts

There are two types of callouts used in our docs, notes and warnings:

Notes

 Note

Notes should identify important pieces of information the reader shouldn't miss.



<Alert title="Note"  type="info" >

Notes should identify important pieces of information the reader shouldn't miss.

</Alert>

Warnings

 Warning

Warnings cover information critical to the reader and highlight potential dangers, especially those that can cause data loss.



<Alert title="Warning" type="danger" >

Warnings cover information critical to the reader and highlight potential dangers, especially those that can cause data loss.

</Alert>

Success

Success callouts are used infrequently, usually in guides with specific end results expected. Use success callouts to differentiate between two binary results.

 Incorrect DNS Configuration

Incorrect vanity domain CNAME required DNS value

 Correct DNS Configuration

Correct vanity domain CNAME required DNS value



<Alert title="Incorrect DNS Configuration" type="danger" icon="remove">

![Incorrect vanity domain CNAME required DNS value](../images/dashboard/wrong-vanity-cname-dns.png)

</Alert>

<Alert title="Correct DNS Configuration" type="success" icon="check">

![Correct vanity domain CNAME required DNS value](../images/dashboard/correct-vanity-cname-dns.png)

</Alert>

Tabs

When working on a document that will cover steps for multiple CMSs, use tabs when possible to condense instructions that need duplication for the different applications.

Here's our WordPress specific copy, and an example snippet:

/**
  * Some WordPress specific thing
  *
  */

Code goes here.

Here's our Drupal 8 specific copy, and an example snippet:

/**
  * Some Drupal 8 specific thing
  *
  */

Some code.

Here's our Drupal 7 specific copy, and an example snippet:

/**
  * Some Drupal 7 specific thing
  *
  */

Some code.


<TabList>

<Tab title="WordPress" id="wp-example" active={true}>

Here's our WordPress specific copy, and an example snippet:

```php
/**
  * Some WordPress specific thing
  *
  */

Some code.
```

</Tab>

<Tab title="Drupal 8" id="d8-example">

Here's our Drupal 8 specific copy, and an example snippet:

```php
/**
  * Some Drupal 8 specific thing
  *
  */

Some code.
```

</Tab>

<Tab title="Drupal 7" id="d7-example">

Here's our Drupal 7 specific copy, and an example snippet:

```php
/**
  * Some Drupal 7 specific thing
  *
  */

Some code.
```

</Tab>

</TabList>

Screenshots

Submit screenshots without additional markup. Don't use Skitch to add an arrow, for example.

GUI

Screenshots are used to reference GUI instructions:

Alt text describing the image



![Alt text describing the image](../images/dashboard/terminus-cli-code-to-commit-dashboard.png)

Terminal

Terminal screenshots should only be used to demonstrate intended output:

Alt text describing the image



![Alt text describing the image](../images/pr-workflow/composer-require-pathauto.png)

Error Messages

Document error messages verbatim as H3s within a Troubleshooting section. Using the exact copy of the error message helps to improve SEO, and making the header an H3 allows the section to be linkable within the table of contents for easy sharing.

RedisException: Redis server went away

The following error occurs when Redis has not been enabled within the Site Dashboard:

RedisException: Redis server went away in Redis->setOption() (line 28 of /srv/bindings/xxxxxxxx/code/sites/all/modules/redis/lib/Redis/Client/PhpRedis.php).

Enable Redis via the Pantheon Site Dashboard by going to Settings > Add Ons > Add > Redis. It may take a few minutes to provision the service.



### RedisException: Redis server went away
The following error occurs when Redis has not been enabled within the Site Dashboard:

 ```none
 RedisException: Redis server went away in Redis->setOption() (line 28 of /srv/bindings/xxxxxxxx/code/sites/all/modules/redis/lib/Redis/Client/PhpRedis.php).
 ```

Enable Redis via the Pantheon Site Dashboard by going to **Settings** > **Add Ons** > **Add** > **Redis**. It may take a few minutes to provision the service.

Panels

Use panels for extraneous but useful information such as troubleshooting sections or pro tips that would be distracting or can be skipped over by a large portion of readers. This is primarily used in an effort to promote readability of a page.



<Accordion title="Panel Title" id="example-panel" icon="wrench">

### Panel Content Header 

This Panel contains additional context, or advanced instructions.

</Accordion>

Tables

You can use markdown tables to describe availability based on service levels before providing instructions on how to enable or use a given feature. For example:

Enable Redis

All plans except for a Basic plan can use Redis. Redis is available to Sandbox site plans for developmental purposes, but Redis will not be available going live on a Basic plan.

PlansRedis Support
Sandbox
Basic
Performance
Elite


## Enable Redis

All plans except for a Basic plan can use Redis. Redis is available to Sandbox site plans for developmental purposes, but Redis will not be available going live on a Basic plan.

| Plans         | Redis Support <Popover content="Available across all environments, including Multidevs." /> |
| ------------- | -------------------------------------- |
| Sandbox       | <span style="color:green"></span> |
| Basic         ||
| Performance   | <span style="color:green"></span> |
| Elite         | <span style="color:green"></span> |

Use ✓ to indicate yes and to indicate no.

Tooltips

Tooltips are a great way to add additional information without cluttering up a section. For example, you can define jargon and even link out to an external resource without being distracting to the reader:

Given two new sites with slugs first-site and second-site, each configuration will result in the following URLs:

  • Subdirectories: example.com/first-site and example.com/second-site.
  • Subdomains: first-site.example.com and second-site.example.com.


Given two new sites with slugs <Popover title="Slugs" content="Generally, are URL friendly descriptions for a post or a page in WordPress. In the context of WordPress Site Networks, a slug is a URL friendly description for a network site." /> `first-site` and `second-site`, each configuration will result in the following URLs:

* Subdirectories: `example.com/first-site` and `example.com/second-site`.
* Subdomains: `first-site.example.com` and `second-site.example.com`.

See Also

This is the optimal place to provide links to external resources on the subject, or internal docs on common processes to follow after completing those above.

See Also



## See Also

- [An internal link](/guides)
- [An external link](https://pantheon.io/blog/)