Code references

We use a variety of formatting to highlight code or other technical language.

When to use code formatting

The following table provides some examples of our use of code format.

Inline code formatting

To format inline code (like maxSampleTimes or TransactionError), surround the text with backtick ` characters.

Multi-line code blocks

To format one or more lines of code, insert three backticks ( ``` ) above and below your code. This essentially acts like the HTML <pre> tag.

Syntax highlighting example

To add syntax highlighting to a code block, insert the language name on the same line as the first three backtacks. Here's an example using some Java code:

This is what the formatting looks like when it's published:

public class SampleTester {

    private String configName;
    private Map<String, Long> maxSampleTimes;

    public SampleTester(String pConfigName) {
        configName = pConfigName;
        maxSampleTimes = new HashMap<>();
    }

Copy

Is syntax highlighting supported for your language?

If you're not sure if our site will format the code snippets for your particular language, do the following:

1. See if your language is included in the default list.

2. If you don't see the language you want to format in the default list, check if it is included in gatsby-config.js (look under prism:). This file lists all the languages we've added beyond the default list.

3. If you still can't find your language, you can make a PR to add it to gatsby-config.js. Before you submit a PR, make sure this language is listed in the Prism site.

   Important

   If your code snippet contains <var> tags, it will not be formatted.

Highlight user input with <var>

The <var> tag is used to highlight areas the user needs to customize the value in a code snippet. For example: you might use <var>YOUR_ACCOUNT_ID</var> to draw a user's attention to a place they'll need to input their account ID.

Follow these guidelines when you use <var> tags:

• Address the reader directly (YOUR_CONFIG_FILE not CONFIG_FILE).
• Use all caps and underscores _ to separate words (also known as SCREAMING_SNAKE_CASE).
• Don't combine them with other punctuation to indicate variables (such as wrapping the text in angle brackets or curly braces).
• Don't overuse them. For example, if you're showing a complete config file where the user is expected to customize many values, a <var> tag on each configurable value is overkill.
• Highlight areas of a code block that are particularly important but not directly procedural-related. Most commonly, <var> is used to highlight New Relic API methods in sample code that contains a lot of "other logic." They're also handy when you want to indicate a bit of code that will be referenced later in a procedure or doc. Examples:
  • Highlighting values in code response that are meant for later use: Activate Azure integrations doc.
  • Highlighting the commands in a large code block example that are New Relic-specific commands, with explanations below: Java API doc.

When you use <var>, you should usually follow the code block with a list of bullets that explain what each API call is doing and link to method syntax.

private void storeItem(long id) {
    Segment segment = NewRelic.getAgent().getTransaction(). startSegment("storeItem");

      segment.reportAsExternal(DatastoreParameters
              .product("H2")
              .collection(null)
              .operation("insert")
              .instance("localhost", 8080)
              .databaseName("test")
              .build());

      // fire and forget
      DB_POOL.submit(() -> {
          segment.end();
          insertData(id);
      });
  }

Do not use a <var> tag for:

• Example code: If the code is meant to be an example, to show the format of the code, and there is not an actual procedure the customer is following, var tags are not needed. A couple reasons for this: 1) The important part of showing an example config file is to show the overall structure of the file, 2) Usually the number of config options present in a file will vary based on whatever the customer wishes to use, so using <var> tags can actually be confusing as it implies that these values must be present. Examples:
  • Example configuration file (or this Java agent config template): if you are showing an example config file that isn't part of a procedure, you shouldn't use the <var> tag.
  • Instrumentation procedure (at bottom of the Java section): the var tag wouldn't be necessary because it's an example, not part of a procedure, and the main goal is seeing the general structure. Also, because it's an example of app code, the concept of user-specific values doesn't have much meaning, because the entire code will vary dependent on how the customer has written their code. (If anything, this would be a potential for using <var> format to emphasize the New Relic functions.)
• Response/output code: If the code is meant to show an expected return, and is not related to a procedure, then var tags shouldn't be used. Here's a doc section (the returned JSON) where var tags are not needed.

For some use cases, highlighting may be a better choice than a var tag.