Description

The docs site will have a "right rail" component that will show a few page-specific items.

The component will look similar to the right rail that appears on the developer site, so we want to abstract it to the theme. This component will continue to utilize its modular architecture to allow for customization of what goes in the right rail. This will also allow site-specific modules that can be used in the right rail.

We also plan to abstract a couple of the common modules that we know are used on all the sites. This includes the contributing module and the last modified module.

NOTE: This is followup of newrelic/docs-website#191 that is specific to the theme work. The docs-site work will be done as a part of newrelic/docs-website#191..

Acceptance Criteria

• Generalized right-rail component added to the Gatsby theme
• GitHub buttons link to the correct locations
• Ability to set contributing guide (default to CONTRIBUTING.md)

Screenshot(s)

Right Rail on Developer Site:

Wireframes for Docs Site:

Summary

We need to set up gatsby-plugin-intl on our gatsby theme or provide a way to render context for the global header and footer, as well as a few other components used by our docs site.

AC

• Gatsby theme allows for language context switching on our sites
• Global header internationalized
• Global footer internationalized
• Code block internationalized
• Feedback internationalized
• Cookie Consent Dialog internationalized

We want to use a consistent color palette across all New Relic Gatsby sites, including dark/light modes. Let's add the CSS variables and colors to ensure consistency.

Description

Opening the search overlay by clicking the search icon in the header does not autofocus the input. It would be great to focus the input so that the user can just begin typing their search query without first needing to click on the input.

Steps to Reproduce

1. Click the search icon in the header
2. Notice the input is not focused

Expected Behaviour

The input is auto focused after opening the search overlay

We are using normalize.css in the developer site to normalize some cross-browser quirks. Let's provide that out of the box as part of this theme. We can use the polished.js normalize function with emotion to handle this for us.

Currently we have branch protection disabled because the opensource bot cannot push to protected branches. @jbeveland27
suggested a workaround that will allow us to enable branch protection and push. This requires us to disable branch protection temporarily, then re-enable once the bot has pushed up changes. This can all be done via GitHub actions.

All New Relic Gatsby sites have the same global header. Let's add the global header to this project.

According to the component audit these are the design specs we should be following:

• Use the icons + size of the icons from the open source site
• On small screens, render the New Relic logo without the text, but keep the circles
• On mobile, always show the dark mode icon, but place it next to the hamburger menu

Summary

We should add prettier and eslint to the project and configure them as needed.

Summary

We need to instrument our CodeBlock component with NR Browser. We need to track the following events:

• copyCodeBlock_click: occurs when a user clicks on the "copy" button

Properties that we want to record with this action:

• modified: whether the code was copied as is or was modified

AC

• instrumented with NR browser agent
• update spreadsheet with action name, additional properties, location implemented, ect.

To comply with our open source standards, let's have the docs team review the README.

Summary

We need to instrument our ResultView component with NR Browser. We need to track the following events:

• swiftypeSearchResult_click: occurs when a user clicks on a search result link

Properties that we want to record with this action:

• href: link clicked
• title: title of result clicked

AC

• instrumented with NR browser agent
• update spreadsheet with action name, additional properties, location implemented, ect.

Summary

We need to instrument our ContributingGuidelines component with NR Browser. We need to track the following events:

• editThisPage_click: occurs when a user clicks on the "edit this page" button
• createAnIssue_click: occurs when a user clicks on the "create an issue" button

Properties that we want to record with this action:

• component: where this takes place, for this one it would be in page tools

AC

• instrumented with NR browser agent
• update spreadsheet with action name, additional properties, location implemented, ect.

Both the developer site and the open source site have the ability to show videos on pages. Let's add this component so we can share them between the 2 sites.

According to component audit, we should make the 3D effect used on the open source site toggleable. The design stays the same otherwise.

Summary

We need to instrument our SwiftypeSearch component with NR Browser. We need to track the following events:

• swiftypeSearch_input: occurs when a user searches

Properties that we want to record with this action:

• search_terms: the text that they inputted when they searched
• num_results: the number of results that came back from the search

AC

• instrumented with NR browser agent

Both the developer site and the open source site have code blocks rendered on various pages. Let's add the implementation from the developer site.

Now that we have a public shared theme library, let's highlight it by listing it on our open source website. Documentation can be found on the wiki. You can use the developer website PR as an example.

Description

In mobile or narrow viewports, the GlobalHeader nav is being cut off in the middle of a nav item.

Screen shot from iPhone 8, Safari browser, iOS 13.6.1

Steps to Reproduce

• Load https://developer.newrelic.com/ on a mobile device or in Chrome using the iPhone 6/7/8 device emulator on via dev tools
• Note in the upper right hand corner the word Community is cut off and the remaining nav items are not accessible

Expected Behaviour

Good question! I suppose I'd expect this either:

1. to have a horizontal scroll
2. to have only 2–3 items selectable, which all fit as full text
3. to have a hamburger-icon and a mobile nav

Since most of the pages using this header will already have their own site-specific hamburger nav, you can probably rule our number 3.

Your Environment

• iPhone 8, Safari browser, iOS 13.6.1

Additional context

• I came across this while working through this open ticket on the Open Source site repo: newrelic/opensource-website#556
• This overfill: hidden rule seems related: https://github.com/newrelic/gatsby-theme-newrelic/blob/develop/packages/gatsby-theme-newrelic/src/components/GlobalHeader.js#L79

Based on a recent component audit from @djsauble, we will be using the button styles from the Developer Website. Let's add the Button component so we can share it across both websites.

Summary

We need to instrument our 404 page with NR Browser. We need to track the following events:

• 404_redirect: occurs when the user is redirected to the 404 page

Properties that we want to record with this action:

• path: path the user were trying to reach

AC

• instrumented with NR browser agent
• update spreadsheet with action name, additional properties, location implemented, ect.

Add the <NewRelicLogo /> that is used in the global header of all sites.

We have some shared Gatsby configuration that we know we want across all New Relic Gatsby projects. This includes plugins such as gatsby-plugin-newrelic, gatsby-plugin-use-dark-mode, gatsby-plugin-robots-txt, etc. Let's centralize the Gatsby configuration as much as possible and only move what makes sense across all New Relic Gatsby projects.

To make our package available to our Gatsby sites, we need to publish the package to NPM.

Let's document configuration options and component APIs so that others looking to use the shared Gatsby theme can do so easily.

When we merge PRs into main, we want to publish a new version of the package to NPM. Using Lerna, we can automate the creation of the changelog, update versions, and publish the package. Note that this will require a manual PR from develop to main.

To comply with our open source standards, lets request a security review of the project to ensure it meets compliance.

Once we have lerna configured in #1 , let's use GitHub actions to automate the release process.

Summary

Add a language toggle that switches the language context by changing the base url (docs.newrelic/en ==> docs.newrelic.com/jp)

Mock Up

AC

• Add optional language toggle to the global header
• Switches the url based on the language toggle
• Languages will be represented by language name

Summary

We need to instrument our SimpleFeedback component with NR Browser. We need to track the following events:

• feedback_click: occurs when a user clicks on one of the feedback buttons

Properties that we want to record with this action:

• feedback: whether the feedback is positive or negative

AC

• instrumented with NR browser agent
• update spreadsheet with action name, additional properties, location implemented, ect.

Like the developer site, let's setup snyk to validate our dependencies.

To ensure consistency, let's add the hamburger menu so that it can be consumed by all New Relic Gatsby sites.

According to the component audit we will want to use aspects of the design from both the developer website and the open source site.

Design requirements:

• Make the hamburger menu smaller than its current size
• Keep the colors used on the open source site in both light and dark modes
• Use rounded instead of square corners like the developer site

The Sign Up buttons to create an account should be more explicit relating to what the user is doing on our DECO sites on the Docs site: "Sign Up" makes sense but on the Dev site and OSS Site the button should be "Start Now".

Acceptance Criteria

1. on the Docs Site, the sign up button should be sign up
2. on the Dev Site, the sign up button should be start now
3. on the OSS Site, the sign up button should be start now
4. All URLs should point to the correct signup form and use the proper UTM source tag identifying where the user came from

Description

We have buttons defined that can be used across New Relic Gatsby sites, but these buttons do not currently have hover states. We need to define hover states for buttons to better provide the experience that these buttons are interactive.

The SEO component is used both in the OS site and the Dev Site, and likely will be used in the Docs site. We should factor this out into the theme.

AC

• Component that adds SEO meta tags for our sites
• Component added to the docs, oss, and dev site

Summary

We need to instrument our GlobalFooter component with NR Browser. We need to track the following events:

• editThisPage_click: occurs when a user clicks on the "edit this page" button
• createAnIssue_click: occurs when a user clicks on the "create an issue" button

Properties that we want to record with this action:

• component: where this takes place, for this one it would be in global footer

AC

• instrumented with NR browser agent
• update spreadsheet with action name, additional properties, location implemented, ect.

We have search inputs on both sites with similar treatment. Let's add this component so we can share both the implementation and the design.

According to the component audit, we want to use the design from the open source site, but with the added functionality of being able to clear the input with an x after typing, like on the developer website.

In addition to the designs, let's consider adding a size prop and allow the component to render as a large size which will match the size on the open source site

With the Docs Site we decided to take a streamline approach to have the submit feedback button pass values in the URL using constants, which prevents the need to use a github issue template. This is very streamlined for a user, and it be cool to do this for the developer site as well and be consistent in our approach to creating issues on both sites.

code
https://github.com/newrelic/docs-website/pull/412/files/9d9091d5dbcf34c6eee855b3f89d7a9b92a53406#diff-22bbe242b6fb50d3a94108b9bf5c8b3df5f928f4d29dea68bc3f7e61d32ee26bR26

considerations

• is this a theme level change or done for each site? Given the The OSS site may need additional issue templates.
• does this makes sense to do for both the Docs Site and Dev Site?
• why does the OSS Site need so many templates linked from create an issue? can we just by pass that.

current issue templates

Docs:
https://github.com/newrelic/docs-website/issues/new/choose

Dev Site:

https://github.com/newrelic/developer-website/issues/new/choose

OSS Site

https://github.com/newrelic/opensource-website/issues/new/choose

Both the developer site and the open source site should have similar global styles (box sizing, font size, etc). Let's add the shared global styles to this project.

To comply with our open source standards via the open source checklist, let's add an explorer's hub topic and link it in the README.

we will first need to update the NPM Package with details https://github.com/newrelic/gatsby-theme-newrelic

And given we don't have any pre-determined guidance for an npm package.

Will post something similar to what we do with the Nerdpacks which is grab some helpful bits from the README and treat it as an initial "press release" in a sense.

• Screenshot + Intro, what is it and why would you want to use it
• How to use it, install/setup (i.e. npm install)
• Link to the repo

Description

To ensure a user cannot discover available pages on our private docs site, we need to ensure sitemaps are not created. Currently the theme is configured to always create a sitemap. We want this to be configurable.

I propose we add a new theme option that will allow us to disable this:

// gatsby-config.js
{
  resolve: '@newrelic/gatsby-theme-newrelic'
  options: {
    sitemap: false
    // ...
  }
}

Acceptance criteria

• Add the option to disable sitemaps
• Sitemaps should default to enabled

Documentation for global color variables

Summary

As noticed in a PR to our developer website, we don't have the best documentation surrounding our global color variables. I wonder if we would be able to link to our color guide / style guide so contributors creating new components are able to reference them!

Like the developer site, we need to generate 3rd party notices to ensure we are using permissively licensed libraries.

We are using local storage to persist the value on each site. From my googling, it doesn’t look like you can share local storage between subdomains, for security reasons. We’d either have to use cookies (which I think allow you to share across subdomains), or we’d need to implement a common iframe that we can communicate with from each site.

By default, each site uses the user’s OS preference. Unless they’ve specifically switched it, they should have the same theme across the sites.

preferably we'd try and solve it via cookies/local storage so it serves everybody consistently.

Description

If the repository is not configured as part of the theme, we should not show any of the GitHub buttons in the footer. This field is currently nullable in the GraphQL schema, but it looks like we do not handle the case where it is null in the footer.

Summary

We need to instrument our ExternalLink and Link component with NR Browser. We need to track the following events:

• externalLink_click: occurs when a user clicks on any external link

Properties that we want to record with this action:

• href: link clicked

AC

• instrumented with NR browser agent
• update spreadsheet with action name, additional properties, location implemented, ect.

Description

When using the variant or similar props for components (such as Button) we expect the user to supply one of the exported types. That said, sometimes the content creators want to use a component and simply supply a string. In the case of the title prop for the <Callout> component, it expects a capitalized string (which is not initially obvious).

We should look through our components and ensure that the user can use an exported type or a string (regardless of casing).

Add a custom event into dashboard so we can track stale issues, and how do we track data on stale issue, and time to resolution, etc. Before attempting to implement discuss with the OSS Team and DTK Team if they do this in anyway with Github actions or Git Hub Stats

Summary

The site version was displayed in the old OSS site footer, and it was cool but offered no utility and when we tried to apply it to the docs site, it was confusing as it wasn't clear what it was actually communication. So we removed it when we standardize the footer for all sites.

Desired Behaviour

To actually make this useful and warrant it to be present in the global footer it would need to

1. indicate it's a site version not docs version, or new relic product version.
2. dynamically link to the current release tag on github so a user could click on it, and see the release notes for that version tag. ex: https://github.com/newrelic/opensource-website/releases/tag/v1.9.2
3. be present in the footer under the footer logo image, vs being on the right side of the footer.

Based on a recent component audit from @djsauble, there are some similarities between the tile components used on both sites. While the design of the content itself differs, there is an opportunity to extract a base component that provides a container for content like this to live. This component would house the box shadows, background color, border, and text color of the card.

Recommendation: Call this component <Surface /> as this is a surface that sits on top of a background (inspiration from Material design)

Summary

Build one Callout component in the theme that takes prop to specify which callout style it should render.

Acceptance criteria

• As a developer I can use a Callout component and specify the type in a prop (tip, important, caution, permissions, pricing)

To ensure consistency, we want to add all typography styles to the theme. These include:

• Font families (primary, secondary, code)
• Links
• Primary and secondary text
• Headers