A well-chosen screenshot or image can greatly improve the readability and clarity of a doc. Too many images or an image that's tough to parse can really slow things down.
- If you're not part of the Tech Docs team and you want to add an image to the docs site, create a GitHub issue.
- If you're a New Relic employee, contact
@heroin the documentation Slack channel.
We want to ensure that sensitive data does not appear in UI screenshots. That's why we recommend that you provide a permalink to a test account. Do not take a screenshot from your New Relic account.
Here are some things to keep in mind when you're creating an image:
- Make sure your image provides useful information at a glance.
- Include a caption with helpful context for the image.
- For screenshot captions, include the path in bold.
- For video captions, include the approximate running time.
Our doc site images are stored in individual
images directories at the root level of each taxonomy category. These
images directories contain all the images used in the docs for that category.
To add an image from scratch:
- Find the images folder for your doc. For example, if your doc lives in the
docs/style-guide/processes-proceduresdirectory, use the
- If the
imagesdirectory does not exist in the directory where your doc lives, use VScode or Finder to create a folder in that directory named
images(must be lower case and plural).
- Place your image in the
imagesdirectory. Give the image a descriptive file name; for example,
fso-ui-overview.pngis much better than
- Continue with the following procedure to embed the image in a doc.
Use markdown to embed an image in a doc. The basic structure:
![alt text](PATH_TO_IMAGE "Image title text")
Here's a filled in example:
![An image showing an overview of the synthetic monitoring UI](./images/synthetics-ui-overview.png "Synthetics UI overview")
To update an image:
- Delete the original image file in the corresponding
- Place the new image file in the same
- Ensure the image file has the same name as the original file.
Descriptive captions help the reader know why the image matters. If it's a screenshot, it's helpful to include the path in bold in addition to a description. For example:
![Dashboards in New Relic One](./images/NR1-dashboards-image.png "Dashboards in New Relic One")<figcaption>**[one.newrelic.com](https://one.newrelic.com) > Dashboards**: Quickly create information-dense custom views into the data that matters most to you with dashboards in New Relic One.</figcaption>
For more help with captions and other supporting text around images, see Guidelines for explaining images.
To use an inline image, add something like this:
The UI includes a multiple app names indicator. ![Multiple app names indicator in New Relic One](./images/new-relic-distributed-tracing-multiapp-icon.png "Multiple apps name indicator in New Relic One")
If the inline image is being used as an icon, always describe it first. When you embed the icon image, follow the image with the word
icon in the text. For example:
Select your app's settings ![settings icon](./images/icon-settings.png "settings icon") icon.
Fixed width, block level images are similar in format to full column width images, except the original image width is smaller than the column width (800px) of a page. It's important that you edit the HTML like you would an inline image. This way the image will be rendered at 100% of the column width and also be responsive to smaller screen sizes.
Use these images when a screenshot is a small part of the page with a width of less than 800px, but when it still needs a caption like a full width image.
Here's an example of the HTML for a fixed width, block level image:
<div style="width: 100%; max-width: Npx;"><img alt="ALT TEXT" height="X" src="IMG_URL" title="FILENAME" width="N"></div><div class="dnd-legend-wrapper" style="width: 100%; max-width: Npx;"><div class="meta"><p>CAPTION TEXT</p></div></div>
You can choose from a variety of icons to include in your docs:
- Feather icons (prefixed with
'fe-), which replace our previous Font Awesome icons
- New Relic icons (prefixed with
- Logos for third-party products (prefixed with
To see if we already have an icon you need, go to:
- Feather.js for
docs-websitein GitHub: These are the Feather icons available in the
docs-websiteproject but are not included in the Gatsby theme.
- Gatsby theme for
docs-websitein GitHub: This is a subset of Feather, New Relic, and product logo icons that are available across the developer and docs sites.
You can use any icons you need in the Gatsby theme or Feather. Currently these locations have separate, non-overlapping buckets of icons.
If your icon appears as an attribute inside another tag, prefix it with
icon as in this example:
If your icon appears inside running text, use the
<Icon> component. Here are some examples:
<Icon name="fe-database" />
- New Relic:
<Icon name="nr-tdp" />
<Icon name="logo-apple" />
If you don't see the icon you want in either the Gatsby theme for
docs-website in GitHub or in the Feather.js for
docs-website in GitHub, you can add a new icon to the Gatsby theme. You can also ask developers to add the icon you want.
Here's an example of adding a
- Go to feathericons.com.
- Download the
databasefeather icon by clicking on the icon itself.
- Once downloaded, open the SVG file in your text editor.
- Copy the "guts" of the SVG, which is everything in between the
<svg>tags. For example, if the SVG is
<svg><path m="1"></path></svg>, then copy only the
- Open the list of feather icons at
- Add an entry for
database, and assign the code from the previous step to it.
- If the icon has multiple paths, include the
<>wrapper around it like you see with other icons.
- Save the
fe- prefix gets added automatically. Once that icon is added, you can use it with the icon component; for example,
<Icon name="fe-database" />.