Community Project header

gatsby-theme-newrelic

This theme contains contains common configuration and shared components used across New Relic Gatsby sites. It is primarily used on the developer and open source websites.

Installation

gatsby-theme-newrelic uses Emotion for styling and depends on its packages. To install this package, add the @newrelic/gatsby-theme-newrelic package and required Emotion packages.

npm:

npm install @newrelic/gatsby-theme-newrelic @emotion/core @emotion/styled @mdx-js/mdx @mdx-js/react @splitsoftware/splitio-react gatsby-plugin-mdx

yarn:

yarn add @newrelic/gatsby-theme-newrelic @emotion/core @emotion/styled @mdx-js/mdx @mdx-js/react @splitsoftware/splitio-react gatsby-plugin-mdx

Configuration

You can configure gatsby-theme-newrelic using the following configuration options:

// gatsby-config.js
module.exports = {
  siteMetadata: {
    siteUrl: 'https://developer.newrelic.com',
    repository: 'https://github.com/newrelic/gatsby-theme-newrelic',
    branch: 'main',
    utmSource: 'developer-site',
  },
  plugins: [
    {
      resolve: '@newrelic/gatsby-theme-newrelic',
      options: {
        sitemap: true,
        layout: {
          contentPadding: '2rem',
          maxWidth: '1600px',
        },
        newrelic: {
          configs: {
            staging: {
              instrumentationType: 'proAndSPA',
              accountId: '1234',
              trustKey: '1',
              agentID: '1234',
              licenseKey: 'your-license-key',
              applicationID: '1234',
            },
            production: {
              instrumentationType: 'proAndSPA',
              accountId: '1234',
              trustKey: '1',
              agentID: '1234',
              licenseKey: 'your-license-key',
              applicationID: '12345',
            },
          },
        },
        i18n: {
          translationsPath: `${__dirname}/src/i18n/translations`,
          additionalLocales: ['jp'],
        }
        robots: {
          policy: [{ userAgent: '*', allow: '/' }],
        },
        splitio: {
          core: {
            authorizationKey: 'my-auth-key',
          },
        },
        tessen: {
          product: 'DEMO',
          subproduct: 'DEMO',
        },
        googleTagManager: {
          trackingId: 'ID_HERE',
          src: 'https://www.googletagmanager.com/gtag/js',
          options: {
            anonymize_ip: true,
          },
        },
        relatedResources: {
          labels: {
            'https://my.website': 'my-website'
          },
        }
      },
    },
  ],
};

Site metadata

gatsby-theme-newrelic makes use of several siteMetadata options. While these are optional, they are highly recommended.

  • siteUrl: Production URL for the site (e.g. https://developer.newrelic.com)
  • repository: The URL for the public GitHub repository hosting the source code for the site.
  • branch: The mainline branch for use when constructing “Edit this page” links (defaults to main). to various mediums within New Relic.
  • contributingUrl: The URL where a user can find contributing guidelines for the site. If this is not specified, it defaults to the CONTRIBUTING.md file in the repo and branch specified in the siteMetadata. If the repository is not specified, this will return null. Set this value to null to disable the default behavior.

Options

sitemap

Toggles the automatic creation of a sitemap. Set this value to false to disable sitemaps.

Default: true

newrelic

Configuration for gatsby-plugin-newrelic. For more details on the available configuration options, visit the documentation.

Default: null

robots

Configuration for gatsby-plugin-robots-txt. These options will be shallow merged with the default value. For more details on the available configuration options, visit the documentation.

Default: { policy: [{ userAgent: '*', allow: '/' }] }

forceTrailingSlashes

Determines whether created pages should include a trailing slash or not. When enabled, this setting also ensures all links that use the Link component will append the trailing slash.

relatedResources

Optional configuration for related resources used in the right rail. Currently only Mdx nodes are supported.

The related resources component is controlled by specific front matter slugs that are defined on a page by setting the front matter for resources. If no resources are available in the page front matter, the component will backfill use the related resource items using Swiftype. See the swiftype options below for more information on customizing the search behavior.

In short, the order of priority for populating content is driven by:

  1. Resources defined via the resources front matter item.
  2. Resources defined from executing a Swiftype search for the page.

Options:

  • labels (object): Map of URLs to their label. This is used to match results displayed in the right rail with the label in the tag displayed underneath the link. Use this to add additional labels not covered by the default set of labels.
  • swiftype (object | false): Configuration used for fetching results from Swiftype for an Mdx node. Set this to false (the default) to disable fetching related resources through Swiftype. If this is disabled, related resources can only be sourced via front matter. If enabled, this takes the following configuration:

    • resultsPath (string) required: Path to the file where Swiftype results will be stored. If the refetch option is set to false (the default), this file will be used to read related resource values for each Mdx node. This file is only written to when refetch is set to true.
    • refetch (boolean): Determines whether to refetch results from Swiftype for every Mdx node during a build. It’s a good idea to only set this on a special build (e.g. a build that happens on a cron job) so that Swiftype is not searched on development or every build on the site.
    • Default: false
    • engineKey (string) required: Swiftype’s engine key used to fetch results from a Swiftype search engine.
    • getSlug (function): Function to get the slug for an Mdx node. Useful if the slug is set from something other than the filesystem. By default, this will use the createFilePath helper to generate the slug for the Mdx node. This function should accept an object as its only argument with a key of node (i.e. getSlug: ({ node }) => { /* do something */ })
    • filter (function): Function to determine whether Swfitype should be queried for the Mdx node. Useful if you only need to get related resources for a subset of nodes on the site. By default, all Mdx nodes are fetched. This function should accept an object as its only argument with a key of node and a key of slug (i.e. filter: ({ node, slug }) => { /* do something */ }).
    • getParams (function): Function that allows you to specify additional params passed to Swiftype when running a search query. Useful if you want to provide additional filters or field boosts. This function should accept an object as its only argument with a key of node and a key of slug.
    • limit (integer): The limit of related resources that should be fetched from Swiftype.
    • Default: 5

tessen

Optional configuration for Tessen tracking.

  • product (string) required: The 4-character product set as nr_product
  • subproduct (string) required: The 4-character subproduct set as nr_subproduct
  • segmentWriteKey (string) required: The write key used for Segment integration.
  • trackPageViews (boolean): Determines whether to track page views via Tessen’s tessen.page action. If this is enabled, you MUST configure the pageView settings to ensure the name and category are propertly instrumented.

    • Default: false
  • pageView (object): Configuration for automatic page view tracking. If trackPageViews is enabled, this MUST be configured to properly instrument page views. If this is not configured, calls to page views will result in a no-op. This takes the following configuration:

    • name (string) required: The name of the page view action. This is passed to tessen.page to track page views.
    • category (string) required: The category of the page view action. This is passed tot tessen.page to track page views.
    • getProperties (function): Function that allows you to specify additional properties that should be instrumented as part of the page view. Takes an object as its only argument with both the location and env as properties on that object. The env is determined by the result of the resolveEnv configuration.
    • ...rest: All other properties will be added as properties to tessen.page.
  • env (object): Environment-specific configuration. This takes the same properties as listed above. These values override the values set above. Useful if you have environment overrides you’d like to apply. The environment is determined based on the valued returned from resolveEnv.

Example

const config = {
  tessen: {
    product: 'DEMO',
    subproduct: 'DEMO',
    trackPageViews: true,
    pageView: {
      name: 'pageView',
      category: 'DemoPageView',
      getProperties: ({ location, env }) => ({
        env: env === 'production' ? 'prod' : env,
      }),
    },
    env: {
      development: {
        trackPageViews: false,
      },
    },
  },
};

resolveEnv

Optional function to determine the environment. Useful to provide a fine-tuned environment name for environment-specific configuration like tessen.

Default:

const defaultResolveEnv = () =>
  process.env.GATSBY_NEWRELIC_ENV ||
  process.env.GATSBY_ACTIVE_ENV ||
  process.env.NODE_ENV ||
  'development';

googleTagManager

Optional configuration for Google Tag Manager. If Tessen is also configured for the site, Google Tag Manager is only used if a user opts out of cookie usage (and thus Tessen is not used at all).

  • trackingId (string) required: The Google Analytics measurement ID.
  • src (string) required: The Google Tag Manager endpoint used to bring Google Tag Manger into the site.
  • options (object): Additional config options to send along with gtag page views and events.

Example

googleTagManager: {
  trackingId: 'ID_HERE',
  src: 'https://www.googletagmanager.com/gtag/js',
  options: {
    anonymize_ip: true,
  },
},

i18n

Optional configuration for internationalization (i18n).

  • additionalLocales: Additional supported for languages other than English (the default language). Currently supports jp.
  • translationsPath: The directory path where the translations will be stored.
  • i18nextOptions: Additional options to pass into i18next that will override the defaults.

These values are used to generate locale-specific pages and to populate a dropdown in the <GlobalHeader /> component.

Example

{
  i18n: {
    additionalLocales: ['jp'];
  }
}

layout

Configuration for the layout.

Options:

  • maxWidth (string): Sets the max width of the layout. Accepts any CSS sizing value (e.g. 1280px).
  • contentPadding (string): Sets the padding value for the content. Accepts any CSS sizing value (e.g. 2rem)

Default: { maxWidth: null, contentPadding: null }

Layout configuration is available in the GraphQL schema which can be queried within the Site type. This is useful when you have other layout elements that need to use the layout configuration.

query {
  site {
    layout {
      maxWidth
      contentPadding
    }
  }
}

These values are also available as global CSS variables. You can access them as:

  • maxWidth: var(--site-max-width)
  • contentPadding: var(--site-content-padding)

prism

Configuration for the prismjs library. This library powers the syntax highlighting used in the CodeBlock component.

Options:

  • languages ([string]): Configure additional languages used for syntax highlighting. These languages will be appended to the list of default supported languages in the theme. For a full list of supported languages, visit the prism documentation.

Default supported languages:

  • css
  • graphql
  • hcl
  • javascript
  • json
  • jsx
  • ruby
  • shell
  • sql
  • sass
  • scss

Example: Add swift as a supported language

module.exports = {
  plugins: [
    {
      resolve: '@newrelic/gatsby-theme-newrelic',
      options: {
        prism: {
          languages: ['swift'],
        },
      },
    },
  ],
};

splitio

Configuration for using split.io with the Gatsby site. For more information on all the available configuration options, visit the split.io SDK docs.

Default:

const DEFAULT_CONFIG = {
  core: {
    trafficType: 'user',
  },
};

NOTE: The core.key configuration option is generated by the theme and therefore ignored. Setting this value will do nothing.

Environment-specific configuration

Use the env option to define environment-specific configuration. The environment configuration will be merged with the top-level configuration.

module.exports = {
  plugins: [
    {
      resolve: '@newrelic/gatsby-theme-newrelic',
      options: {
        splitio: {
          core: {
            trafficType: 'user',
          },
          env: {
            development: {
              core: {
                authorizationKey: 'my-development-key',
              },
            },
            production: {
              core: {
                authorizationKey: 'my-prod-key',
              },
            },
          },
        },
      },
    },
  ],
};

The env key will be taken from process.env.GATSBY_ACTIVE_ENV first (see Gatsby environment variables for more information on this variable), falling back to process.env.NODE_ENV. When this is not available, then it defaults to development.

You can resolve the env by using the resolveEnv function:

module.exports = {
  plugins: [
    {
      resolve: '@newrelic/gatsby-theme-newrelic',
      options: {
        splitio: {
          // ...
          resolveEnv: () => process.env.BUILD_ENV,
        },
      },
    },
  ],
};

Components

Used to add a marketing banner to a page.

import { Banner } from '@newrelic/gatsby-theme-newrelic';

Props

Prop Type Required Default Description
children node yes Content to be displayed in the banner.
onClose function yes Handler called when the user clicks on the “close” button.
visible boolean yes Determines if the banner is visible to the user or not

Example

<Banner visible={visible} onClose={() => setVisible(false)}>
  <h1>Hello, World!</h1>
</Banner>

Button

Styled buttons used to draw emphasis on clickable actions.

import { Button } from '@newrelic/gatsby-theme-newrelic'`

Props

Prop Type Required Default Description
variant enum yes Configures the variant of the button. Must be one of Button.VARIANT.LINK, Button.VARIANT.PRIMARY, Button.OUTLINE, or Button.VARIANT.NORMAL
size enum no Configures the size of the button. Can be configured to Button.SIZE.SMALL
as React element no button Render the button as a different base element. Useful when you want to style links as buttons.

Additional props are forwarded to the underlying element specified by the as prop.

Examples

<Button variant={Button.VARIANT.PRIMARY} onClick={() => console.log('Hello')}>
  Say hello
</Button>

Render a link as a button

import { Link } from '@newrelic/gatsby-theme-newrelic';

// ...

<Button as={Link} to="/page-2" variant={Button.VARIANT.PRIMARY}>
  Page 2
</Button>;

Callout

Callouts direct your attention to information of special importance or to information that doesn’t fit smoothly into the main text.

  • Caution: Screams at you that this could cause a crash or cost you data loss beyond the task at hand.
  • Important: Urges awareness that this could impair the task at hand or cost you time if you ignore the text.
  • Tip: Whispers to you that this is nice to know, like a shortcut, best practice, or reminder.
import { Callout } from '@newrelic/gatsby-theme-newrelic'`

Props

Prop Type Required Default Description
className string no Adds a className to the callout. Useful if you need to position the callout within its parent element.
variant enum yes Configures the variant of the callout. Must be one of Callout.VARIANT.CAUTION, Callout.VARIANT.IMPORTANT, Callout.VARIANT.TIP, Callout.VARIANT.COURSE
title enum no Set the title text. Defaults to variant name. You may hide the title by passing null as the value.

Examples

<Callout variant={Callout.VARIANT.CAUTION}>Be careful!</Callout>

Hide the title

<Callout variant={Callout.VARIANT.CAUTION} title={null}>
  Be careful!
</Callout>

CodeBlock

Used when rendering code blocks on a page.

import { CodeBlock } from '@newrelic/gatsby-theme-newrelic';

Props

Prop Type Required Default Description
autoFormat boolean no true* Determines whether to auto format the code using prettier. true will force code formatting to occur. false will force disable code formatting. If left empty, code formatting will only run on a subset of supported languages (see below)
children string yes The code to be rendered in the code block
className string no Adds a className to the outer container of the code block. Useful if you need to position the code block within its parent element.
components object no Swap out the elements used when rendering various elements of the code block. See the “Configurable components” guide below to learn more about this prop.
copyable boolean no true Determines whether to render a copy button for the content inside the code block.
fileName string no The file name associated with the code rendered by the code block. Useful if the code block is used as part of tutorial.
formatOptions object no Configuration options given to the formatCode utility function to auto-format the code block.
highlightedLines string no Specifies which lines in the code block should be highlighted. See the examples below on for information on how to format this string.
language string no Configures the language used for syntax highlighting. Must match one of the languages or its aliases from prismjs. To learn more about configuring supported languages, visit the prism configuration section.
lineNumbers boolean no false Determines whether to show line numbers inside the code block.
live boolean no false Determines whether the code block is live-editable or not. Useful when used in conjunction with the preview option, though not required.
preview boolean no false Determines whether a live preview is displayed using the value in the code block. Useful in conjunction with the live option to allow the user to edit the code snippet.
scope object no Configures the variables available as globals for the live preview. By default, only React is injected. To find out more about how the scope prop works, visit the react-live documentation.

Auto code formatting

Out of the box, the CodeBlock component will use prettier to format code for a subset of languages. These include:

  • jsx/javascript
  • html
  • graphql
  • json
  • css/sass/scss

To force formatting for another language, set the autoFormat prop value to true. To force disable code formatting, set the autoFormat prop value to false.

NOTE: If you choose to force enable code formatting for a language not listed above, you may need to use the formatOptions prop to set the proper plugins.

Configurable components

The CodeBlock is a component made up of several underlying components. There are cases where the default components may not be suitable for the needs of the site. The components prop allows you to specify your own custom components in place of the defaults to tailor component rendering for that component.

Each custom component is given all the props that would otherwise be passed to the default component. It is highly recommended to use the props given to the custom component.

The following components can be customized:

Preview

By default, the built-in Preview component uses the LivePreview component from react-live. Overriding this component may be useful if you need to, for example, render the preview inside of a shadow DOM root element which allows style isolation without polluting the global CSS namespace.

It is highly recommended that you render the LivePreview component within your custom component. It will be very difficult to see the live preview otherwise.

Prop Type Description
className string Includes the default styles for the preview pane. Forward this prop to the root of your custom component to maintain a consistent style.

Examples

const codeExample = `
import React from 'react'

const Button = (props) => (
  <button className='button' {...props} />
)
`;

const Documentation = () => (
  <CodeBlock language="jsx" fileName="src/components/Button.js">
    {codeExample}
  </CodeBlock>
);

Line highlighting

const codeExample = `
import React from 'react'
import PropTypes from 'prop-types'

const Button = (props) => (
  <button className='button' {...props}>
    {props.children}
  </button>
)

Button.propTypes = {
  children: PropTypes.element
}

export default Button
`;

const Documentation = () => (
  /*
   * Highlight multiple lines by comma-separating the line numbers.
   * Include a range of lines by using a `-` between the line numbers.
   */
  <CodeBlock language="jsx" highlightedLines="1,6,10-12">
    {codeExample}
  </CodeBlock>
);

Custom Preview component

import { LivePreview } from 'react-live';
import root from 'react-shadow';

const styles = `
.button {
  display: inline-flex;
  align-items: center;
  justify-content: center;
  padding: 0.5rem 1rem;
  font-size: 0.875rem;
  background: none;
  cursor: pointer;
}
`;

// This component will be used in place of the default `Preview` component in
// the `CodeBlock`. Here we are using the shadow DOM to provide style isolation
// for the `button` class defined by the CSS in the `styles` variable above.
const CustomPreview = ({ className }) => (
  <root.div>
    <style type="text/css">{styles}</style>
    <LivePreview className={className} />
  </root.div>
);

// The button implementation we will be using when rendering the live preview,
// provided via the `scope` prop.
const Button = ({ children, ...props }) => (
  <button className="button">{children}</button>
);

const codeSample = `
<Button>Click me</Button>
`;

const Documentation = () => (
  <CodeBlock
    preview={true}
    components={{ Preview: CustomPreview }}
    scope={{ Button }}
  >
    {codeSample}
  </CodeBlock>
);

Collapser

This element is used to reveal or hide content associated with it. Use in conjunction with a CollapserGroup when using multiple Collapsers in tandom.

import { Collapser } from '@newrelic/gatsby-theme-newrelic'`

Props

Prop Type Required Default Description
children node yes The content that will be hidden or revealed when the user interacts with the Collapser.
defaultOpen boolean yes false Determines if the Collapser should default to its open state.
id string no An HTML id attribute that will be attached to the Collapser title. Useful if you want to deep link to the Collapser.
title string | React element yes The text that will be rendered on the interactive button used to toggle the open state on the Collapser.

Examples

import { Collapser } from '@newrelic/gatsby-theme-newrelic';

<Collapser title="The Ruby Agent API">
  This is some information about the Ruby Agent. You'll have to interact with
  the Collapser to see me.
</Collapser>;

Multiple collapsers

import { Collapser, CollapserGroup } from '@newrelic/gatsby-theme-newrelic';

<CollapserGroup>
  <Collapser title="Collapser 1">
    The first collapser! I will be hidden by default.
  </Collapser>
  <Collapser title="Collapser 2" defaultOpen>
    The second collapser! The user will see this content by default.
  </Collapser>
</CollapserGroup>;

CollapserGroup

Used in conjunction with multiple Collapsers to group them together.

import { Collapser, CollapserGroup } from '@newrelic/gatsby-theme-newrelic'`

Props

Prop Type Required Default Description
className string no Adds a className to the collapser group. Useful if you need to position the collapser group within its parent element.
children React element yes The set of Collapser elements that will be rendered as part of the CollapserGroup.

Examples

import { Collapser, CollapserGroup } from '@newrelic/gatsby-theme-newrelic';

<CollapserGroup>
  <Collapser title="Collapser 1">
    The first collapser! I will be hidden by default.
  </Collapser>
  <Collapser title="Collapser 2" defaultOpen>
    The second collapser! The user will see this content by default.
  </Collapser>
</CollapserGroup>;

ContributingGuidelines

Used to display contributing information for the current page. This is meant to be used as a section inside of the PageTools component.

To ensure this component leverages its full potential, please ensure the following siteMetadata fields are configured:

  • branch
  • contributingUrl
  • repository

NOTE: If the contributingUrl is not configured, it will use the default value as specified in the siteMetadata section.

import { ContributingGuidelines } from '@newrelic/gatsby-theme-newrelic'`

Props

Prop Type Required Default Description
fileRelativePath string no The relative file path of the current page. This will be used by the “Edit this page” link.
pageTitle string no The title of the current page for use in a new GitHub issue.

Examples

<PageTools>
  <ContributingGuidelines fileRelativePath="src/pages/index.js" />
</PageTools>

CookieConsentDialog

A dialog box that pops up asking for cookie consent. This component renders at the bottom of the screen and provides options for accepting or denying cookies.

import { CookieConsentDialog } from '@newrelic/gatsby-theme-newrelic';

Example

const MyLayout = () => (
  <>
    <GlobalHeader />
    <GlobalFooter />
    <CookieConsentDialog />
  </>
);

CreateIssueButton

Pre-defined GitHubIssueButton used specifically for the “Create issue” button in the ContributingGuidelines and GlobalFooter components.

import { CreateIssueButton } from '@newrelic/gatsby-theme-newrelic';

Props

Prop Type Required Default Description
pageTitle string no Title of the page where the user clicked the “Create issue” button. Used to pre-populate the issue.

All other props are forwarded to Button component.

Example

import { Button, CreateIssueButton } from '@newrelic/gatsby-theme-newrelic';

<CreateIssueButton
  pageTitle="Demo"
  size={Button.SIZE.SMALL}
  variant={Button.VARIANT.OUTLINE}
/>;

Used in combination with Dropdown.Toggle, Dropdown.Menu, and Dropdown.MenuItem to create a dropdown.

import { Dropdown } from '@newrelic/gatsby-theme-newrelic';

Props

Prop Type Required Default Description
align enum no “left” The position of the menu arrow. Must be either left, right, or center.
children node yes Components used for the dropdown.
import { DropDown, Button } from '@newrelic/gatsby-theme-newrelic';

const Example = (
  <Dropdown align="right">
    <Dropdown.Toggle variant={Button.VARIANT.NORMAL}>Menu</Dropdown.Toggle>
    <Dropdown.Menu>
      <Dropdown.MenuItem>Item 1</Dropdown.MenuItem>
      <Dropdown.MenuItem>Item 2</Dropdown.MenuItem>
      <Dropdown.MenuItem>Item 3</Dropdown.MenuItem>
    </Dropdown.Menu>
  </Dropdown>
);

Used within a Dropdown component to render a button that can toggle whether or not the dropdown menu is visible.

Props

Prop Type Required Default Description
size enum no The size prop for the underlying Button component.
variant enum yes The variant prop for the underlying Button component.
children node no Content used to render the toggle

Used within a Dropdown component to render the menu that is shown when the dropdown is open.

Props

Props Type Required Default Description
children node yes Content rendered inside the dropdown menu. Should consist of Dropdown.MenuItem components.

Used within a Dropdown.Menu component (within a Dropdown component) to render an individual dropdown menu item.

Props

Props Type Required Default Description
href string no A path that, if supplied, will be used as a Link.
onClick function no An optional click event handler that is triggerd when the component is clicked.
children node yes Content for the MenuItem.

Used to render links that navigate outside of the website. This component is a shortcut on top of the target="_blank" and rel="noopener noreferrer" attributes and provides no out-of-the-box styling.

import { ExternalLink } from '@newrelic/gatsby-theme-newrelic';

Props

All props are forwarded to the underlying a tag with the exception of the target and rel props.

Example

<ExternalLink href="https://newrelic.com">Link to New Relic</ExternalLink>

EditPageButton

Button used to link to the current page in GitHub. Used for the “Edit page” button in the ContributingGuidelines and GlobalFooter components.

import { EditPageButton } from '@newrelic/gatsby-theme-newrelic';

Props

Prop Type Required Default Description
fileRelativePath string yes Relative filepath of the current page.
instrumentation Instrumentation yes Config for the component instrumentation when the button is clicked. See the values below for a desciption on what is allowed.

All other props are forwarded to Button component.

type Instrumentation = {
  component: string;
};

Instrumentation

The following fields are available for instrumentation:

  • component (string) required - The name of the component where this button is used. Helps to understand where in the site the button is clicked.

Example

import { Button, EditPageButton } from '@newrelic/gatsby-theme-newrelic';

<EditPageButton
  fileRelativePath="src/content/docs/apm.mdx"
  size={Button.SIZE.SMALL}
  variant={Button.VARIANT.OUTLINE}
  instrumentation={{ component: 'ContributingGuidelines' }}
/>;

FeatherSVG

SVG wrapper for feather icons. This is useful when shadowing feather icons to ensure all feather icons have consistent props/styles applied to them.

NOTE: When using this component, you should to spread all props to it.

import { FeatherSVG } from '@newrelic/gatsby-theme-newrelic';

Props

Prop Type Required Default Description
children node yes The “guts” of the feather svg definition

Additional props are forwarded to the svg tag.

Example

const ChevronDownIcon = (props) => (
  <FeatherSVG {...props}>
    <polyline points="6 9 12 15 18 9" />
  </FeatherSVG>
);

GitHubIssueButton

Button used to create issues on GitHub. This component depends on the repository and siteUrl fields configured in site metadata.

import { GitHubIssueButton } from '@newrelic/gatsby-theme-newrelic';

Props

Prop Type Required Default Description
labels string[] no Labels that should be prepopulated for the issue. NOTE: This labels must be created in the repository where this button links to.
issueTitle string no The value that will pre-populate the issue title.
issueBody string no The value that will pre-populate the issue body.

All other props are forwarded to Button

Environment information

As a convenience, this component attaches environment information to the issue body to allow for easier debugging. This eliminates the need for a section in the issue body asking for environment information from the user filing the issue.

The information gathered is:

  • Page URL
  • Browser name and version
  • Operating system name and version
  • Device type (mobile, tablet, etc.), vendor and model

If the browser environment is unable to be determined, these values are simply set to “Unknown”.

Example

import { Button, GitHubIssueButton } from '@newrelic/gatsby-theme-newrelic';

const ISSUE_BODY = `
## Description

[NOTE]: # (Tell us some information!)
`

<GitHubIssueButton
  labels={['bug']}
  issueTitle="Bug found"
  issueBody={ISSUE_BODY}
  size={Button.SIZE.SMALL}
  variant={Button.VARIANT.OUTLINE}
>
  Found a bug!
</GitHubIssueButton>

Renders the global footer used on all New Relic Gatsby sites. This component utilizes the layout configuration from the theme to size itself and the siteMetadata for the repository URL.

NOTE: The logo displayed in the footer is a generic to New Relic logo, but can be changed with shadowing.

import { GlobalFooter } from '@newrelic/gatsby-theme-newrelic';

Props

Prop Type Required Default Description
className string no Additional className for the component.
fileRelativePath string no The relative path to the markdown file for the current page. If not supplied, the edit link will not be shown
pageTitle string no The title of the current page for use in a new GitHub issue.

Example

<GlobalFooter fileRelativePath={'/src/content/foobar.md'} />

Renders the global header used on all New Relic Gatsby sites. This component utilizes the layout configuration from the theme to size itself.

import { GlobalHeader } from '@newrelic/gatsby-theme-newrelic';

Props | Prop | Type | Required | Default | Description | | --------- | ------ | -------- | ------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------- | | editUrl | string | no | | Used by the edit page link in the global header to link to a GitHub URL where a user can edit the page’s source. If omitted, the edit page link will be excluded. |

Gatsby configuration

The GlobalHeader component consumes configuration defined for the theme. In order to make the most of the GlobalHeader component, it is recommended that you configure the following values in gatsby-config.js:

// gatsby-config.js

module.exports = {
  siteMetadata: {
    // Used to set the link that matches the current site as active
    siteUrl: 'https://developer.newrelic.com',
    // Used to create a link to the issues page from the global header
    repository: 'https://github.com/newrelic/gatsby-theme-newrelic',
  },
  plugins: [
    {
      resolve: '@newrelic/gatsby-theme-newrelic',
      options: {
        // Define the layout properties to ensure the global header aligns
        // nicely with the rest of the content
        layout: {
          maxWidth: '',
          contentPadding: '',
        },
      },
    },
  ],
};

Examples

import { graphql, useStaticQuery } from 'gatsby';

const Layout = () => {
  const { data } = useStaticQuery(graphql`
    query {
      site {
        siteMetadata {
          repository
        }
      }
    }
  `);

  return (
    <GlobalHeader
      editUrl={`${data.site.siteMetadata.repository}/src/components/layout.js`}
    />
  );
};

HamburgerMenu

Used as the toggle for mobile views to show and hide the mobile navigation.

import { HamburgerMenu } from '@newrelic/gatsby-theme-newrelic';

Props

Prop Type Required Default Description
className string no Additional className for the component.
isOpen boolean yes false Determines whether the HamburgerMenu is considered open or closed.
onToggle function yes Handler called when the user interacts with the hamburger menu. This handler should be responsible for toggling the isOpen state of the hamburger menu.

Examples

import React, { useState } from 'react';

const MobileMenu = () => {
  const [isOpen, setIsOpen] = useState(false);

  return (
    <HamburgerMenu
      isOpen={isOpen}
      onToggle={() => setIsOpen((isOpen) => !isOpen)}
    />
  );
};

Icon

Used to render icons on the website. This component utilizes a subset of the Feather icon set. To add additional icons for use in your website, use component shadowing. See the “Shadowing” section below for an explanation on how to use this feature.

import { Icon } from '@newrelic/gatsby-theme-newrelic';

Props

Prop Type Required Default Description
name enum yes The name of the icon that will be rendered. See the full list of available icons in the “Available icons” section below.
size string no 1em The size of the icon. The value can be any CSS sizing value.

Additional props are forwarded to the underlying svg element.

Available icons

Feather

  • fe-chevron-down
  • fe-cloud
  • fe-copy
  • fe-edit
  • fe-external-link
  • fe-filter
  • fe-github
  • fe-loader
  • fe-moon
  • fe-pen
  • fe-search
  • fe-sun
  • fe-thumbsdown
  • fe-thumbsup
  • fe-x

New Relic

  • nr-tdp
  • nr-fso
  • nr-ai

Logos

  • logo-apple
  • logo-android

Shadowing icons

Because this theme only provides a subset of the feather icon set, you may need to add additional icons for use in your website. You can use component shadowing to do so. When shadowing the icon set, YOU MUST include the default set of icons in order for the built-in components to work properly.

When shadowing an icon set, defined the icons using the unprefixed name. The gatsby theme will automatically prefix the icons for you depending on the icon set. For example, to add the chevron-right icon, define its name as chevron-right, not fe-chevron-right. This icon will be available to the Icon component as fe-chevron-right.

The following icons sets can be shadowed:

  • Feather

    • File path: src/@newrelic/gatsby-theme-newrelic/icons/feather.js
    • Prefix: fe
  • New Relic

    • File path: src/@newrelic/gatsby-theme-newrelic/icons/newrelic.js
    • Prefix: nr
// src/@newrelic/gatsby-theme-newrelic/icons/feather.js
import React from 'react';
import defaultIcons from '@newrelic/gatsby-theme-newrelic/src/icons/feather';
import { FeatherSVG } from '@newrelic/gatsby-theme-newrelic';

export default {
  ...defaultIcons,
  'chevron-right': (props) => (
    <FeatherSVG {...props}>
      <polyline points="9 18 15 12 9 6" />
    </FeatherSVG>
  ),
};

// To use this icon, use the prefixed name:
<Icon name="fe-chevron-right" />;

Example

<Icon name="fe-copy" size="1rem" />

Layout

Layout components used to wrap the page content. Used as a container for the layout subcomponents.

For more information on the layout subcomponents, see the following for more details:

import { Layout } from '@newrelic/gatsby-theme-newrelic'`

Props

Prop Type Required Default Description
className string no Additional className for the component.
children node no Content used for the layout. These should be layout subcomponents.

Examples

<Layout>
  <Layout.Sidebar>
    <Logo />
    <MyNavigation />
  </Layout.Sidebar>
  <Layout.Main
    css={css`
      display: grid;
      grid-template-columns: minmax(0, 1fr) 320px;
      grid-template-areas: 'content page-tools';
      grid-gap: ${contentPadding};
    `}
  >
    <Layout.Content>
      <h1>Hello, world</h1>
    </Layout.Content>
    <Layout.PageTools>
      <ContributingGuidelines fileRelativePath={fileRelativePath} />
    </Layout.PageTools>
  </Layout.Main>
  <Layout.Footer fileRelativePath={fileRelativePath} />
</Layout>

Layout.Content

Used for displaying the body of the page. It has a grid-area set to content to allow for grid customization.

Props

Prop Type Required Default Description
className string no Additional className for the component.
children node no Content used for the layout. These should be layout subcomponents.

Examples

<Layout.Content>
  <h1>Hello, world</h1>
</Layout.Content>

Layout.Footer

Wraps the GlobalFooter component for use inside the layout.

Props

All props are forwarded to the GlobalFooter component.

Examples

<Layout.Footer fileRelativePath={fileRelativePath} />

Layout.Main

Wraps the main content area in the layout.

NOTE: For single-column pages, the Layout.Content component should be used as the single child of this component to ensure the props Swifttype attributes are added for the body of the content. For layouts that use Layout.PageTools, you will need to specify the grid used for the layout.

Props

Prop Type Required Default Description
className string no Additional className for the component.
children node no Content displayed inside the main content area. For single-colum layouts, the Layout.Content should be the only child.

Examples

<Layout.Main>
  <Layout.Content>
    <h1>Hello, world</h1>
    <p>Here is where the main content of the page goes!</p>
  </Layout.Content>
</Layout.Main>

Layout with page tools

<Layout.Main
  css={css`
    display: grid;
    grid-template-columns: minmax(0, 1fr);
    grid-template-areas: 'content page-tools';
  `}
>
  <Layout.Content>
    <h1>Hello, world</h1>
    <p>Here is where the main content of the page goes!</p>
  </Layout.Content>
  <Layout.PageTools>
    <ContributingGuidelines fileRelativePath={fileRelativePath} />
  </Layout.PageTools>
</Layout.Main>

Layout.PageTools

Wraps the PageTools component for use inside the layout.

Props

All props are forwarded to the PageTools component.

Examples

<Layout.PageTools>
  <ContributingGuidelines fileRelativePath={fileRelativePath} />
</Layout.PageTools>

Layout.Sidebar

Sidebar displayed inside the layout. This should contain the primary navigation used for the site.

Props

Prop Type Required Default Description
className string no Additional className for the component.
children node no Content displayed inside the main content area. For single-colum layouts, the Layout.Content should be the only child.

Examples

<Layout.Sidebar>
  <Logo />
  <MyNavigation />
</Layout.Sidebar>

Provides a “smart” link to link to other URLs. This provides a unified component between a Gatsby Link and an external link. This component will pick between a regular anchor tag and a Gatsby link depending on whether the URL is a relative or external url.

This component will automatically convert absolute URLs that link to pages within the same site to relative links. This ensures a smooth user experience for all linked pages on the site.

This component can be used as a replacement for the built-in Link component in Gatsby since it wraps it.

import { Link } from '@newrelic/gatsby-theme-newrelic'`

Props

Prop Type Required Default Description
to string yes The URL to link to. If this is a relative path, it will use the Gatsby Link component. If it is an external URL, it will use a regular anchor tag.

All additional props are forwarded to either the Link component or the anchor tag depending on whether it is a relative or absolute URL.

Examples

// Can be used as a relative link to other pages in the site
<Link to="/page-2">

// Can also be used to link to external URLs
<Link to="https://gatsbyjs.com">

// If the link is absolute, but the origin matches the `siteMetadata.siteUrl`,
// it will smartly convert this to a relative path.
<Link to="https://developer.newrelic.com/page-2">

MarkdownContainer

Container used to wrap markdown content. Provides spacing and additional styles necessary for documents rendered via markdown or MDX.

import { MarkdownContainer } from '@newrelic/gatsby-theme-newrelic';

Props

Prop Type Required Default Description
children node yes Content that will be rendered inside the markdown container. This is usually an MDX component.
className string no Additional className for the MarkdownContainer
dangerouslySetInnerHTML string no Same as React’s dangerouslySetInnerHTML. Useful when rendering a compiled markdown string inside this container.

Example

MDX

<MarkdownContainer>
  <MDX body={body} />
</MarkdownContainer>

Markdown

<MarkdownContainer dangerouslySetInnerHTML={markdown} />

MDX

Utility to render MDX content on a page. Provides out-of-the-box shortcodes for commonly used components.

import { MDX } from '@newrelic/gatsby-theme-newrelic';

Props

Prop Type Required Default Description
body string yes The compiled MDX string to be rendered for the page. This is usually the body property on an MDX node in Gatsby.
components object no Provides shortcodes for MDX documents. Use this to add additional components or override the default components.

Using MDX

When using MDX, it is HIGHLY RECOMMENDED to wrap the content with the MarkdownContainer component to provide the additional styles and proper spacing. If you would like to render additional components within the MarkdownContainer and want to match spacing, use the following CSS variables:

  • --block-element-spacing: Provides proper spacing for block elements (callouts, code blocks, etc.)
  • --text-spacing: Spacing used between paragraphs of text. Use this for textual elements in the document (i.e. unordered/ordered lists)

Default components

The MDX component ships with a set of default mapped components. Where possible, this component uses the MDX component variants for block level components to provide proper spacing.

For more information on the set of available shortcodes mapped to built-in elements (such as a), see the MDX documentation

The following shortcodes are available by de