Link guidelines

Whenever possible, include hyperlinks where relevant within the text itself. Avoid creating lists of doc links in the For more help section, because it is harder for future writers to determine why they matter.

Link text

Follow these guidelines when writing text for hyperlinks:

• Labels: Make sure each link in the document has a unique, meaningful text label. Do not use the same text string to label different links.
• Location: Include a clear, concise text label to identify where the link goes. Give extra context if you're linking to an external site. Why are you sending someone there?
• Click here: Do not use "click here" or other meaningless link labels.
• "Link test:" Read just the links, without the surrounding text. Can each stand alone as a clear description of where the link goes if that is all the user looks at on the page?
• Avoid URL prefixes: If you're sending users to an address where you want to use the URL as the link text, drop the https: and www. prefixes from the link text. For example, [github.com](https://github.com) not [https://github.com/](https://github.com). Or [github.com/newrelic/docs-website](https://github.com/newrelic/docs-website/) not [https://github.com/newrelic/docs-website](https://github.com/newrelic/docs-website/).

Take the link test for these three examples. The last is the best for readers looking for information on configuring PHP, because the link clearly identifies it, without having to read anything else on the page.

Support links

Never include a hyperlink to the Support email address. This prevents spam and ensures customers use the ticket submission form to create tickets so they receive the correct support priority. If you need to tell customers to contact support, use this instead:

Get support at [support.newrelic.com](support.newrelic.com).

Docs site ("internal") links

When creating links to other documents on the docs site, include only the path from /docs forward. Do not include https://docs.newrelic.com, or the site will treat it as an external link.

Here is an example:

[/docs/agents/php-agent/configuration/php-agent-newrelic-ini-settings](PHP agent (newrelic.ini) settings

Anchor links

If your link includes an anchor (for example, #inivar-scope), use the complete, current doc path it uses. Some browsers do not retain anchors with redirects.

When creating or editing an HTML id for an anchor link, follow these guidelines:

• Only use lower case when creating new IDs.
• Use hyphens - to separate words. Don't use _ underscores.
• When reorganizing a doc, try to preserve incoming anchor links where possible. Be mindful that when you delete a level two heading ##, it will break any links to that heading.
• Avoid changing an existing anchor ID, because we may be monitoring traffic to it from our internal New Relic account.

External links

When creating links to websites outside the docs.newrelic.com subdomain (including newrelic.com, one.newrelic.com, discuss.newrelic.com), the docs site automatically includes code that opens the link in a new tab.

In addition to the link text guidelines in this doc, here are some other things to keep in mind when linking to external sites:

• Think about the best way to future-proof your links. If possible, point to a top-level domain, but not if it reduces the usefulness of the link. How stable is the content you're linking to? Is the URL likely to change?
• Make sure your link is as useful as possible. What value are you trying to add to the document? Can that information be shared in another way?
• Help the reader understand why you're linking to this external source. Is it a useful reference, such as a list of time zones? Is it a way to save someone time, such as linking directly to a hard-to-find file?
• Make sure that your link is generally accessible. Are you linking to an external site that requires authentication, such as a private GitHub repo?

Linking to an arbitrary (non-heading, non-collapser-entry) section in a doc

H2 and H3 headings and collapsers have their own built-in IDs that you can link to. But sometimes you may want to link to a paragraph or to a table entry. In general, avoid this, and instead, link to headings and collapsers.

Occasionally it's useful to link to a specific entry in a table, or a very important paragraph in a conceptual explanation. To do that, place a <span> tag around some text, using this format:

<span id="name">your text</span>

And then link to it using the standard anchor link format.