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.
For this... | Why use code? | Example |
---|---|---|
File paths and file names | Using code helps paths and file names stand out, and ensures clarity about the exact file name. | The agent looks for |
NRDB event names and attributes | Many attribute names (such as | To analyze APM errors, use the |
Method names | Using code formatting for method names is standard practice. | To initialize the APM agent, use |
URLs you don't intend to be clicked | Using code formatting hints to the user that they may need to customize or tweak the URL to ensure it works for them. | In your web browser, navigate to the minion Overview page at |
Command line utility names | If you think a reader or translator might confuse a command with a general English word, use code.
| To install the utility, use |
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.
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
notCONFIG_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.
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
<mark>
format to emphasize the New Relic functions.)
- 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
- 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.
Highlight a code section with <mark>
Use the <mark>
tag to highlight areas of a code block that are particularly important but not directly procedural-related. Most commonly, <mark>
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.
Here are two examples of highlighting:
- 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 <mark>
, 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.