Last updated November 19, 2024

This article contains the style guidelines for the Heroku Dev Center. If you’re writing or updating a Heroku Dev Center article, follow this guide to ensure a consistent reading experience for users.

Dev Center Markdown Overview

Dev Center articles use GitHub Flavored Markdown. Here’s a brief syntax example:

## Section header

Use the H2 header (`##`) for your article's top-level sections. Dev Center parses these titles to construct the article's table of contents. Don’t use H1 headers (`#`) in your article. Here’s some more text, and a [link](https://heroku.com/).

![A descriptive title (required for images)](https://example.com/test.png)

### Subheader

Here’s an unordered list:

* Bullet 1
* Bullet 2

And some output from a command:

```term
$ echo hi
hi
```

Now some code:

```ruby
puts "hello"
```

And a table:

|  A  |  B  |
| --- | --- |
|  1  |  2  |
|  3  |  4  |

> note
> You can also include [styled notices](#styled-notices) like this one.

Bold

Only bold text when used with backticks to reference UI elements. Use italics instead for emphasis.

Capitalization

Use title capitalization for all titles and headings. For example, use:

Heroku Postgres Maintenance Windows

Instead of:

Heroku Postgres maintenance windows

Use the dictionary to determine proper capitalization, and refer to this summary of capitalization rules in the Salesforce Style Guide.

Code Snippets

As expected, code is a significant part of Dev Center documentation. The Dev Center supports syntax highlighting for all languages supported on Heroku.

Begin the first line of a fenced code block with three back ticks ``` and an optional language identifier:

```ruby
puts "hello world"
```

This snippet renders as:

puts "hello world"

The following are the language identifiers for major languages on Heroku:

Terminal Commands

Use the term code block identifier for terminal commands and output. Precede terminal commands with a $ prompt indicator.

```term
$ heroku create
Creating blooming-water-4431... done
http://blooming-water-4431.herokuapp.com/ | git@heroku.com:blooming-water-4431.git
Git remote heroku added
```

This snippet renders as:

$ heroku create
Creating blooming-water-4431... done
http://blooming-water-4431.herokuapp.com/ | git@heroku.com:blooming-water-4431.git
Git remote heroku added

Be sure to show sample output from commands to provide context and successful execution expectations. To improve clarity, show only portions of output that are relevant to the reader’s understanding of the command.

Heroku CLI Commands

Many Heroku CLI commands support the --app option, which specifies the Heroku app to run the command against. When you show a Heroku CLI command in a code block, always include this option if the command supports it:

$ heroku config --app example-app

Use example-app as the app’s name unless the article already uses another particular app name for illustrative purposes.

Inline Code

Surround inline filenames, commands, and code with backticks. This formatting ensures that `file.rb` renders as file.rb.

Don’t precede command-line commands by a prompt symbol when shown inline.

Example Names

Heroku App Names

When naming apps, use example-app as the name of the application, leading to a Heroku hostname of example-app.herokuapp.com.

Domains

When naming a domain, use www.example.com as an example domain name.

IDs

When demonstrating a command with an ID, use angle brackets (<id>) to replace the ID.

Secrets

Some articles require secrets, such as database connection strings or AWS S3 keys.

Create an abstract string that shows the form of the secret, rather than sharing an actual secret. For example:

Use:

postgres://user:password@ec2-1-2-3.compute-1.amazonaws.com:5432/databasename

In other cases, using a fake secret instead of an abstract string is clearer for the reader. For example, a fake bearer token is shown here instead of an abstract string so the user can see its format better: term curl -X POST https://hc-central.heroku.com/auth/example-app \ -H "Authorization: Bearer 86b831b4-c3e8-4a3f-93bf-ca9ffa6dfdc8"

Graphics

Images succinctly convey hard-to-understand concepts and provide a visual break from large blocks of text. Use them to emphasize important concepts and support the larger article structure.

Most graphics are self-explanatory. If your image requires a description, describe it on a new line before the image instead of adding a caption below it. You can add images in Markdown like this:

Some text description of this image:

![Image title](https://s3.amazonaws.com/bucket/image.jpg)

Always include an image title within the [] brackets.

Screenshots

Follow these steps when taking screenshots for your article:

• Set up your screenshot using “real” looking data.
• Resize your browser window to 1024 x 768 or smaller.
• Minimize unused space and try to omit anything that’s likely to become outdated later.
• Take the screenshot.
• Add callouts if needed.
• Add a 1-pt black border.
• Adjust the image to meet these guidelines:
  • DPI: 200
  • Width in pixels: 800 px maximum.
  • Width in inches: 4"

Instruction Steps

If a user must complete steps in a particular order, number them. Use complete sentences with proper punctuation.

For tasks where most steps are 1-2 sentences, create a numbered list, such as:

1. Click the Settings tab in the Heroku Connect dashboard.
2. Click Import/Export Configuration.
3. Click Export.
4. Click Export in the confirmation window to download the file.

See References to the User Interface for notes on formatting UI elements for your instructions.

Italics

Use italics sparingly for emphasis. You can make text italic by wrapping them in * or _. For example,

*Text to italicize.*

Renders as:

Text to italicize.

Links

Link to Other Dev Center Articles

Link to other Dev Center articles by specifying the article’s slug (the final component of its URL). Here’s how to link to the Dynos and the Dyno Manager article:

The [dyno manager](dynos) is responsible for keeping dynos running.

Result:

The dyno manager is responsible for keeping dynos running.

Link to a Section Within the Same Article

Link to headers within the same Dev Center article like so:

Here’s a link to the [Code Snippets](#code-snippets) section of this article.

Result:

Here’s a link to the Code Snippets section of this article.

Link to a Section in a Different Article

Link to headers within the another Dev Center article like so:

Here’s a link to the [Install the Heroku CLI](heroku-cli#install-the-heroku-cli) section of [The Heroku CLI](heroku-cli) article.

Result:

Here’s a link to the Install the Heroku CLI section of The Heroku CLI article.

Link to External Sites

When you link to an external site, use its full URL:

Here’s a link to the [Twelve-Factor App](https://12factor.net/).

Result:

Here’s a link to the Twelve-Factor App.

Lists

Use ordered lists for instruction steps, unless the steps are too lengthy.

Use unordered lists sparingly. Avoid nesting bullet points.

Introduce a list with the beginning of a sentence followed by a colon. If the introduction is a complete sentence, end it with a period.

Capitalize the initial word of each line item, whether it’s a fragment or a full sentence. End sentences with periods. For example:

Research how your language or framework addresses seeds. For instance:

• The Ruby gem Faker and JavaScript/Node library Faker.js generate fake data.
• Libraries like Rails and Node.js’s Sequelize have conventions for writing seeds.

For fragments, omit the period. For example:

The best practices in this article assume that you have:

• Node.js and npm installed
• An existing Node.js app
• A free Heroku account
• The Heroku CLI

References to the User Interface

Some Dev Center articles refer to a user interface, particularly ones that involve Dashboard, Data, or Connect. Here’s an example:

To see the add-ons provisioned and attached to an application, visit the Heroku Dashboard. Click the name of the app or click the Resources tab when viewing an app.

When writing about a user interface element, place the name of the UI component between ***` and `***.

The formatting for the previous example looks like:

**`Resources`**

Use this formatting for consistency and to ensure that those elements aren’t translated into other languages.

Sections

Use the H2 header (##) for your article’s top-level sections. Dev Center parses these titles to construct the article’s table of contents. Don’t use H1 headers (#) in your article.

Styled Notices

Dev Center supports three specially styled notices:

• warning
• note
• callout

Use the warning notice to advise the reader when a particular action is destructive or irreversible:

>warning
>Removing an add-on destroys all associated data.

This snippet renders as:

Use the note notice to highlight information that is critical to the reader’s comprehension of a topic, but not dangerous:

>note
>While Heroku Git is convenient for deployment, it's not intended to be a stable git repository. Use [GitHub](https://github.com/), [GitLab](https://about.gitlab.com/), [BitBucket](https://bitbucket.org/), or another version control system to track your codebase.

This snippet renders as:

Use the callout notice to present information that is relevant to the topic, but not critical to the reader’s comprehension:

>callout
>You can’t authenticate with the Heroku HTTPS Git endpoint using your Heroku email and password. The Heroku HTTPS Git endpoint only accepts API-key-based HTTP Basic authentication. Use an API key as described in this section.

This snippet renders as:

Table of Contents Structure

Dev Center automatically generates an article’s table of contents from its h2 (## in markdown) elements.

The following set of headers results in a TOC that includes Header 1 and Header 2:

## Header 1
### Header 1.1
## Header 2

Trademarks, Brand Names, and Feature Names

Capitalize “Heroku”. When referring to the URL, use “heroku.com”.

The Heroku trademark is a proper adjective. Don’t modify the spelling or structure. For example, don’t use “Heroku’s” or “Heroku-ish”.

Use “Salesforce org”, not “Salesforce organization”.

Capitalize product brand names to set trademarks apart from other words. Here are some examples:

• Apache Kafka for Heroku
• Heroku Add-ons
• Heroku Buildpacks
• Heroku Buttons
• Heroku CI
• Heroku CLI
• Heroku Connect
• Heroku Dev Center
• Heroku Dynos
• Heroku Elements Marketplace
• Heroku Enterprise
• Heroku Key-Value Store and Shield Heroku Key-Value Store
• Heroku Pipelines
• Heroku Postgres
• Heroku Private Spaces
• Heroku Shield Private Spaces
• Salesforce Connect

If it’s obvious from context that a product or feature is from Heroku, you can omit “Heroku”.

Capitalize feature names only if they are brand names. If there’s a marketing campaign around it, it’s also appropriate to capitalize a feature name that’s not a brand name.

When referring to trademarks owned by other companies, follow their trademark guidelines.

Additional Guidelines

This article contains the style guidelines for the Heroku Dev Center. When writing an article, you must also adhere to the Voice and Tone and Content Guidelines. For more info, see Writing a Dev Center Article.