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.
If you're linking to the product, see our style guide page on UI paths.
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?
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.
"Link test" example
To learn more about renaming your PHP app, click here.
To learn more about renaming your PHP app, see New Relic's config docs.
To learn more about renaming your PHP app, use the PHP agent (newrelic.ini) settings.
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 [https://support.newrelic.com](support.newrelic.com).
When creating hyperlinks to other documents on the Docs site, include only the path from
/docs forward. Do not include
https://docs.newrelic.com or Drupal will treat it as an external link.
Here is an example:
[/docs/agents/php-agent/configuration/php-agent-newrelicini-settings](PHP agent (newrelic.ini) settings
If your link includes an anchor (for example,
#inivar-scope), use the complete, current doc path in Drupal, not a redirect URL. 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
- 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.
- Do not change an existing anchor ID without checking to see if it receives traffic.
When creating hyperlinks to websites outside the docs.newrelic.com subdomain (including newrelic.com, one.newrelic.com, and other subdomains), the docs site automatically includes code that opens the link in a new tab.
While keeping in mind the link text guidelines above, 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?