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 syntax

The docs site uses Markdown inline link syntax:

[link text](https://example.com)

If you're linking to another page on the docs site, you should use "relative" links (omitting the docs site's https://docs.newrelic.com root URL):

[link text](/docs/category-path/doc-path/)

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).

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.

Deep links into product

When directing users to parts of the product, you want to deep link when possible. Deep linking encourages users to go into the product and, if they haven't created an account yet, prompts them to sign up. This is more effective than just linking to a sign up page. However, deep linking into the UI only works sometimes and it takes some experimenting to find a good permalink.

Here's an example workflow using the Logs UI:

1. From your work account, go to the part of the UI you want to link. Grab the complete URL as it appears naturally.
2. Open an incognito window and paste in the URL.
3. Edit the URL to a cleaner state. We want simple URLs when possible. For logs, this looks like this: https://one.newrelic.com/logger.
4. New Relic will prompt you to sign in, so sign in with a non-work email.

The URL sends you to the logs page and auto-completes account ID identifying information. That page is deep linkable.

If the simple URL doesn't work, you have two extra steps. Here's an example workflow where the simple URL doesn't work. We'll use this URL to work off of:

https://one.newrelic.com/marketplace/install-data-source?account=[ACCOUNT_ID_HERE]&begin=168917[…]APPLICATION%27%29&state=1ecc7248-ff69-a838-0c8e-d5eaa8bc5431

1. After finding your URL, open an incognito window and paste in the simple URL: https://one.newrelic.com/marketplace/install-data-sourceThis page doesn't load with the simplified URL.

2. Test this URL by removing the account=[ACCOUNT_ID_HERE] part of the slug. The new URL will look like this:

   https://one.newrelic.com/marketplace/install-data-source?&begin=168917[…]APPLICATION%27%29&state=1ecc7248-ff69-a838-0c8e-d5eaa8bc5431

   Copy

3. Paste that URL in a new incognito window. It'll take you to the correct page with your unique account ID populated in.

4. Confirm with another writer that this URL works by having them open the URL with the account ID number removed. They should use a non-work email.

If the URL fails in either case, it's likely that that part of the product UI is not deep linkable. In that case, link one.newrelic.com to the All capabilities page, then describe the path per our pathing guidelines.

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?