newrelic/developer-website

Source code for the New Relic Developer Site.

developer.newrelic.com

View known vulnerabilities

🚀 Local development

You can serve this site locally to quickly see your changes and additions before you PR them. To get started, navigate into your new site’s directory and start it up, as follows.

cd developer-website/
yarn
yarn start

Your site is now running at http://localhost:8000!

Dependencies

Node v17 is used in this project as specified in .nvmrc.

📝 Unit tests

To run the unit tests, run yarn test in the terminal. If you would like to have the tests automatically re-run, use yarn run test:watch.

🌎 Community

New Relic hosts and moderates an online forum where customers can interact with New Relic employees as well as other customers to get help and share best practices. If you're looking for configuration help or more information about New Relic's products, please visit the New Relic Explorers Hub.

Like all official New Relic open source projects, there's a related Community topic in the New Relic Explorers Hub.

🚧 Contributing

We welcome contributions to the New Relic Developer Site. Please review our Contributors Guide prior to submitting any code.

Keep in mind when you submit your pull request, you'll need to sign the CLA via the click-through using CLA-Assistant. You only have to sign the CLA one time per project. If you have any questions, or to execute our corporate CLA, required if your contribution is on behalf of a company, please drop us an email at [email protected].

🚦Code of conduct

Please review and agree to our Code of Conduct prior to submitting any code.

🐛 Issues / enhancement requests

Please submit any issues or enhancement requests using one of our Issue Templates. Please search for and review the existing open issues before submitting a new issue to prevent the submission of duplicate issues.

CI/CD

fetch-observability-packs

• Purpose: This workflow pulls down Observability Packs from the GraphQL API, writes them to src/data/observability-packs.json (overwriting any previous content), and commits that file to the main branch.
• Trigger: Schedule, 12am everyday

developer-website's Issues

[Open source checklist] Add Explorers Hub support link to readme

Description

As called for in the open source checklist, we need to add a specific explorer's hub link to the repo's readme.

AC

1. create a topic on the explorer's hub for the Developer Site, similar to how the OSS Site has done it
2. Add this link to the site readme under community, similar to how the OSS Site has done it

[Site Walkthrough] Add hover state to the "Show 12 more guides" button

Add a nice hover state similar to how the OSS site does it for the guide tiles. https://opensource.newrelic.com/

[Site Walkthrough] Drop the images at the bottom of the Developer Champions page

See screenshot:

Mapping synthetics events on a map

• Leverage Leaflet lib
• Map IP address to lat/lng
• Align Synthentics event query results with mapping data

Add API references to sub navigation to Explore APIs primary navigation

Description

We should reference these tools in V1 Docs

• https://rpm.newrelic.com/api/explore
• https://api.newrelic.com/graphiql

We'll need a new Side Navigation item called: Try our APIS

Mock up

Try our APIS

• New Relic API Explorer (external link icon)
• NerdGraph API Explorer (external link icon)

Design Notes:

• Since these are external links, let's be sure to add the external link icon to the end of each to make their behavior clear
• @djsauble to provide a side navigation icon to represent APIs

Format data to use data object on chart components

How to work with the NR1 Table components

We need a tutorial on this: https://developer.newrelic.com/client-side-sdk/index.html#components/Table

Add hcl syntax highlighting to code blocks

Is your feature request related to a problem?

hcl syntax highlighting is missing from code blocks.

Describe why this important to you

Some of our code samples are hcl

Understanding URL states

• Updating and Reading URL state for sticky URLs
• Getting entity id from NerdletState
• Getting time window from PlatformState

Add a component library overview page that explains what the component library is

User Story

Add a component library overview page that explains what the component library is and also provides a link to docs creators so they can easily link to the main library page.

Acceptance Criteria

1. @djsauble to provide design
2. @mmfred to provide content
3. When clicking on the component library sub navigation I am taking to this new overview page.

[Site Walkthrough] Replace stock photos on the Developer champion page

Ask Haney if we have any stock photos we can use to replace the grainy photos on the developer champion page.

Create a Build your Environment getting started guide

Description

Michelle was going to put something together such as: https://www.gatsbyjs.org/tutorial/part-zero/

To help a new developer get up and running with their dev environment.

Env setup and getting started guide ideas

1. install Node.js
2. manage multiple versions of node.js with nvm
3. install all React dependencies
4. install CLI
5. install any other New Relic dependencies
6. Accessing Repos

Change repo branch from "master" to main

Description

To coincide with the industry trend to remove the term master from technology we should rename our github master branch to main.

Likely steps:

1. Communicate with devs and docs folks about the change to using the main branch and intended timing of the switch.
2. Merge latest from master into main (main branch was already created along and an corresponding amplify branch build)
3. Get all open PRs to point to main
4. Update amplify to point developer.newrelic.com to main.

5. Delete the master branch from the repo 6. Communicate with devs and docs folks to confirm the change is in place.

Add horizontal scrolling to code samples within a step?

Is your feature request related to a problem? Please describe.

If I add a long code comment to a code snippet that is within a step, the code box expands so wide that it squeezes the width of the actual step. The result is that I have different widths for different steps.

You already seem to offer this horizontal scrolling for code snippets outside of the components. Could you just implement this for steps, too?

Describe the solution you'd like

Could you implement a horizontal scroll bar for code snippets? This way, if I were to add a long comment, it would not change the width of the associated step.

Describe why this important to you

This would allow us to include wide code snippets and maintain consist widths for step text.

Additional context

[Open source checklist] Automate generation of third party notices file

Description

As asked for in the open source checklist, we need to automate the generation of our THIRD_PARTY_NOTICES.md.

nr1-browser-analyzer

Captions for videos and images

Is your feature request related to a problem? Please describe.

When I use the Intro component, it pushes the video to the right side of the screen--away from the text that explains it. If we had a captions component, readers could easily identify the purpose of videos and images.

Describe the solution you'd like

Could you add a component that allows users to add captions that appears immediately below videos or images? Sometimes, we may need captions below images in Steps, but this is less common.

Describe why this important to you

Captions are a common feature of website layout when images are not near the text that explains them.

Additional context

Here's an example where the video is not close to the text that introduces it:

Add quick tip video to NerdGraph guide

Summary

What type of documentation change are you suggesting?

Add quick tip video of NerdGraph Explorer to how-to guide: https://master.dlyi50rq9kt6c.amplifyapp.com/collect-data/get-started-nerdgraph-api-explorer

Please use this embed script
`

<iframe src="https://fast.wistia.net/embed/iframe/oo1lbw991a?videoFoam=true" title="How to Get Started with NerdGraph API Explorer Video" allow="autoplay; fullscreen" allowtransparency="true" frameborder="0" scrolling="no" class="wistia_embed" name="wistia_embed" allowfullscreen msallowfullscreen width="100%" height="100%"></iframe>

<script src="https://fast.wistia.net/assets/external/E-v1.js" async></script>`

[stretch] Make a component to standardize image sizes for guides

Description

I think we should standardize on the image size and then build a component for that eventually.

[Stretch] On iOS, the global navigation can be "pulled" over the site content

Description

When "pulling" down on a page to trigger a refresh, you can pull the global navigation (top-bar) off the top of the page and over the main content area. See attached screenshot.

Steps to Reproduce:

1. Go to the site on a iOS device
2. Pull down on the page as if to refresh it

Expected Result

The top-bar should be locked to the top. When pulling down on the page to refresh, the whole page should be pulled down.

Set up dashboards / Review alerts dashboard

Description

Once we have the agent installed, and have our SLIs defined, we should create some NR dashboards to help us monitor the success of the developer site. We will need one dashboard for troubleshooting (mapped to our alert policies) and another dashboard for the overall success (mapped to our SLIs).

As a reminder, here are the DevEx OKRs that are relevant to the developer site:

• 20% increase in usage in page views (6,300 page views currently)
• >25% bounce rate (57% currently)
• Number of CLI downloads hits 200 for the year
• 2 other NR teams and 5 non-NR individuals contributing

Acceptance Criteria:

• Dev Site success dashboard created based on previously defined SLIs
• Review trouble shooting dashboard made in previous MMF
• Troubleshooting dashboard is linked in runbooks

Add template for general purpose content

It seems we need a template type for pages that are not part of some wider grouping.

Is your feature request related to a problem? Please describe.

When adding the terms and conditions page, the guide template was available and does the trick for this very moment to just get the page in place, but it is not something we'd want to show up in some auto display of all guide type files.

Describe the solution you'd like

The first thought on my mind is something like a "General" or "Generic" template.

Describe why this important to you

I'm riding on an assumption that at some point it will be important that only actual guide pages use the GuidesTemplate for technical reasons (auto populating guide overview pages, etc).

Additional context

n/a

Simplify the number of options presented to the user when opening a bug/issue

Description

Very meta! When the user clicks "Clear an issue" they are taken to a screen with four options. It's not clear which one to use. Let's simplify this to be something like...

• Open a bug
• Request something new

Acceptance Criteria

The issue types should be

• Bug Report
• Enhancement Request
• Documentation Request

[Site Walkthrough] Make developer champions badge larger on the developer champions page

Markdown formatting inside <Important> component not rendering

Description

Bold (two asterisks) or file name formatting (backticks) don't seem to render when they are inside the tags.

This behavior applies to text inside components whether or not they are inside steps.

Steps to reproduce

1. Create an block.
2. Insert text that is surrounded by two asterisks on either side.
3. Preview locally.

Expected behavior

I expected bold or file name formatting inside components.

Screenshots

[Open source checklist] Add auto generated CHANGE_LOG.md

Description

This ticket is created in reaction to Open Source Release Checklist.

Inspiration could be drawn from the actions based approach in the open source site's repo. You can see the change log history commits come from the bots https://github.com/newrelic/opensource-website/commits/develop/CHANGELOG.md

Acceptance Criteria

• Merged to master triggers an automatic commit to update the change log based on our semantic commits.
• Only commits of fix or feat type show up in the change log.

[Open source checklist] Add Snyk status badge to readme

As called for in the security post linked from the open source checklist, we need to display the Snyk status badge on our repo’s readme. Here is a PR that was getting that started before finding out that we are blocked on it until the repo is public.

Can't move image to the right column of a <Step>

Description

There’s no apparent way to move an image to the right column in blocks.

Steps to Reproduce

• Create a block
• Add an image anywhere
• Check layout

Expected behavior

I would expect that images appear on the right side, or that at least can be moved there if needed, with automatic resizing (kind of what happens with videos in the Intro block).

Screenshots

[Site Walkthrough] Add hover state (box shadow, movement) to the "Get inspired" tiles

Add a nice hover state similar to how the OSS site does it for the guide tiles. https://opensource.newrelic.com/

Create new layout components for overview pages

When converting the workflow automation page, its clear that we need some additional layout components for overview-type pages. This page does not really have an intro, but really 4 sections, each with equal treatment. The <Intro /> component does a bit too much since these aren't really 4 intro sections, but plain markdown is a bit too unformatted for this kind of page. It would be nice to provide either a new template and/or additional components for content contributors to use to be able to handle these types of layouts a bit better.

Starting page for components badly needed

Is your feature request related to a problem? Please describe.

It's impossible to link in any general way to the component reference content because there's not page for just introducing the component ref. In creating overview pages or even "Related info" links, I have regularly left out the component ref even though it's fundamental to any kind of app building, because the only option is to link to a random component. That would be more confusing than helpful.

Describe the solution you'd like

I know there are a lot of needs for the component ref. This is a simple intro page that can help describe what users will find in the reference and how they'll use it. Something with a consistent link that we can point to as a place to get started.

Describe why this important to you

As mentioned, without a general way to link to the component reference, I am choosing not to link to it, despite that it is fundamental to building apps.

Additional context

You don't have to create the content, just the page.

[Site Walkthrough] Add sub-header before the list of tiles on each overview page (e.g. Automate workflow guides)

User Story
As a user it would be nice to have a sub header on the overview pages that gives me a little more information before I diving in the list of guides.

Acceptance Criteria

1. A design is provided by @djsauble
2. @mmfred reviews this new section to ensure it’s communicated well to a user.

Can't move image to the right column of a <Step>

Description

There’s no apparent way to move an image to the right column in blocks.

Steps to reproduce

1. Create a block.
2. Add an image anywhere.
3. Check layout.

Expected behavior

I would expect that images appear on the right side, or that at least can be moved there if needed, with automatic resizing (kind of what happens with videos in the Intro block).

Screenshots

Provide last update on each page of the DevEx Site

Description

As a user I would like to know when a page was last updated so it’s clear to me the recent update of content.

Acceptance Criteria

• a new section is added to the bottom of the page above the site footer
• add page last modified {month, day, year} to each page on the site. this indicates the last time the page was updated

Adding third-party data

Code blocks have fixed height

Description

Code blocks do not bode well with one-liners due to their fixed width and height. On the other hand, they don't take all the vertical space available if the description on the left column is long enough: they stay at the same height.

Steps to reproduce

1. Create a block.
2. Add a code block in Markdown.
3. Add a one-liner (like a bash command) or a longer snippet.

Expected behavior

I would expect the code block to adapt to the length of the code, being constrained only by its parent container's height (unless the code block is on the left side of a step).

This would also help when inserting code blocks on the left side of a step without line numbering and code copy.

Screenshots

All guides should have a distinct time, not a range

Issue

This guide reads 15-30 minutes. Let's be consistent. Either introduce the notion that guides have a distinct time, not a range, so this would be 30 min. Or all guides have a range.

Acceptance Criteria:

Any guide with a time range should be set to a distinct time value

Images and code snippets are stretched out of <Step> blocks

Description

I’ve a couple tips / blocks after closing . They show with full width, and with overstretched code blocks. Screenshots outside of Intro or Step sections are full width.

You can see how it looks like here: https://github.com/newrelic/developer-website/blob/ea6d0eda0d8a62f37a8fe5a12e4acf6250ad3abf/src/markdown-pages/get-started-nerdgraph-api-explorer.mdx

Steps to reproduce

1. Create an .mdx guide.
2. Add an image and a code block outside of a block.
3. See the stretched layout.

Expected behavior

I would expect a max. width (proportional) to be in place.

Screenshots

Storing data into Nerdstorage

Automatic code formatting is a bit too aggressive

Description

Attempting to write a code block with paths in it ends up rendering with space in between the directories. Take the following example written in markdown:

```
cd /home/Users/jerelmiller/code
```

This will render as a code block to the screen with spaces in between the /.

cd / home / Users / jerelmiller / code

prettier is being used under the hood to auto-format code blocks and prettify them. We should consider only enabling auto code formatting for JavaScript and JSX content rather than trying to format all code.

Steps to reproduce

1. Write any code block in a guide using the above text.

Expected behavior

The code renders the text as expected without the additional formatting between the directory names.

Environment

  System:
    OS: macOS 10.15.4
    CPU: (12) x64 Intel(R) Core(TM) i7-8850H CPU @ 2.60GHz
    Shell: 5.7.1 - /bin/zsh
  Binaries:
    Node: 10.15.1 - ~/.nvm/versions/node/v10.15.1/bin/node
    Yarn: 1.19.1 - /usr/local/bin/yarn
    npm: 6.12.1 - ~/.nvm/versions/node/v10.15.1/bin/npm
  Languages:
    Python: 3.7.4 - /Users/jmiller/.pyenv/shims/python
  Browsers:
    Chrome: 83.0.4103.106
    Firefox: 75.0
    Safari: 13.1
  npmPackages:
    gatsby: ^2.20.25 => 2.20.25 
    gatsby-image: ^2.3.4 => 2.3.4 
    gatsby-plugin-google-tagmanager: ^2.3.3 => 2.3.3 
    gatsby-plugin-manifest: ^2.3.5 => 2.3.5 
    gatsby-plugin-mdx: ^1.2.11 => 1.2.11 
    gatsby-plugin-meta-redirect: ^1.1.1 => 1.1.1 
    gatsby-plugin-offline: ^3.1.4 => 3.1.4 
    gatsby-plugin-react-helmet: ^3.2.4 => 3.2.4 
    gatsby-plugin-robots-txt: ^1.5.1 => 1.5.1 
    gatsby-plugin-sass: ^2.2.3 => 2.2.3 
    gatsby-plugin-sharp: ^2.5.6 => 2.5.6 
    gatsby-plugin-sitemap: ^2.4.3 => 2.4.3 
    gatsby-remark-images: ^3.3.8 => 3.3.8 
    gatsby-source-filesystem: ^2.2.4 => 2.2.4 
    gatsby-transformer-remark: ^2.7.3 => 2.7.3 
    gatsby-transformer-sharp: ^2.4.6 => 2.4.6 

Implement Dark Mode in the New Dev Ex Site

User Story

As a developer I would like to be able to toggle the devex site to dark mode and then back to light mode.

Acceptance Criteria

• Offer a Dark Mode toggle similar to the OpenSource Site
• Offer a way to toggle light mode / dark mode in the UI
• Toggle can go in the Right Corner of the Top Navigation

Code snippets: Disable line numbers by default

Description

I often find myself adding lineNumbers=false to code snippets manually. I think they add little value, and we don't really reference line numbers.

Bold formatting not rendering inside <Important>

Description

If I have bold text inside , the text is not bold.

Steps to reproduce

Here is the code that shows the problem:

  <Step>

Click ***Use NerdGraph***.

<Important>If you don't see any launchers, click ***Your applications***.</Important> 

![Use Nerdgraph launcher](../images/nerdgraphquery-guide/use-nerdgraph-launcher.png)

  </Step>

Expected behavior

I expect the text marked with three asterisks to be bold inside the note.

Screenshots

Here's a screenshot:

Component library navigation "resets"

When you are browsing the component library, and you scroll down to select one of the charts, e.g. Area Chart, the left nav "resets" itself to the top.
https://master.dlyi50rq9kt6c.amplifyapp.com/components/area-chart

1. Open component library
2. Scroll to chart arear
3. Select a chart.
4. observe left-nave behavior.

Add table styles for markdown tables

Is your feature request related to a problem? Please describe.

Currently, there are no styles for markdown tables in content pages. Creating content using markdown tables should be styled nicely.

Describe the solution you'd like

Style the tables rather than leave them unstyled.

Describe why this important to you

The unstyled tables do not look super great and its hard to process information. By adding some styling, this should help the reader digest the information a bit easier.

Additional context

Here is a screenshot of the current unstyled table.

Add space between final step and general text.

Is your feature request related to a problem? Please describe.

When I have text that follows a step, I don't think the reader can tell where the step stops and the general text begins because the two are not spaced apart (vertically).

Describe the solution you'd like

I would prefer at least a double line feed or some other type of separator so users don't confuse text that follows a procedure (and may summarize it) with the final step of a procedure.

Describe why this important to you

This will aid in user comprehension and reduce friction.

Additional context

Fix the developer champions logo and move it to the right side and make it full height

Description

We want to move the developer champions logo to the right side side and make it full height. @djsauble had some suggestions for this!

See which account a Nerdpack is deployed to

nr1 nerdpack:info -i --profile

Animated GIFs are not supported

Description

Adding GIF animations produce a broken image. This is a known issue of gatsby-image, as acknowledged by its author here.

Steps to reproduce

1. Add a GIF file to the /src/images folder.
2. Reference the file from any mdx guide.
3. Load the page in your browser.
4. A broken picture icon appears instead of the GIF.

Expected behavior

Animated GIF should work. Or there should be at least of way of importing them directly, bypassing gatsby-image.

Provide cookie consent confirmation

Description

The OSS put intercom in and it will be released with that widget, but Joel has taken it out

We don't seem to be using it the Core Docs site, but it's on the old Dev Site and the marketing site.

So in the short term to get a cookie consent message into the new DevSite we have decide to leverage what Daniel Golden is building and hopefully can borrow that code (see attached video)

User Story

As a user I should be clearly told the DevSite uses Cookies and have option of accepting or denying this.

Implementation Details:

• Use the same experience found on the OSS site. (opensource.newrelic.com)

• Use the same gatsby plugin that the OSS site uses: https://www.gatsbyjs.org/packages/gatsby-plugin-gdpr-cookies/

• Prompt a user when they first go to the site and let them know about cookies.

• If they accept, allow cookies to be used

• if they reject, disable cookies from being used.

• See the OSS Repo for more implementation details.

newrelic/opensource-website#484
https://github.com/newrelic/opensource-website/pull/522/files
https://github.com/newrelic/opensource-website/tree/danielgolden-feat/cookie-approval-dialog

Release coordination

We will want to release this feature with the OSS Site team on the same day when we return from the long 4th O' July weekend. Ideally we'd release on July 6th / 7th

Add an Introduction to NewRelic Page

Description

As part of the intro to the site for a user who may not be familiar with New Relic it would be nice to have a New Relic Overview Page, and also have this in the primary navigation.

Acceptance Criteria

0. This page will need a design as it's slightly different from other pages we have on the site today.
1. This will need some marketing language which we can source from existing materials we have.
2. Add a Navigation item: New Relic One
3. Place Nav item at the top of the Side Nav
4. Build a content page that explains what New Relic is at a high level.