Gatsby New Relic Themes

This repo contains Gatsby themes used by New Relic Gatsby sites, including:

• docs.newrelic.com - GitHub repository
• newrelic.com/instant-observability - GitHub repository
• developer.newrelic.com - GitHub repository
• opensource.newrelic.com - GitHub repository

Installation

In your terminal:

git clone git@github.com:newrelic/gatsby-theme-newrelic.git
cd gatsby-theme-newrelic
yarn

Getting started

You can use the Demo Site included to test out changes to the theme. It's a much smaller package to build and serve than our other sites, so it's ideal for testing out changes to plugin behaviour, styling and our component library.

To run the Demo Site, simply use either of the following commands:

yarn start

...or...

yarn workspace demo develop

It should only take ~30 seconds to build and you should see...

success Building development bundle

...in the terminal, then you can visit http://localhost:8001 in your browser :)

Locally developing with another gatsby site

In the case that you would like to develop locally and test out your changes with another gatsby site, for example docs-website, you can symlink your local version of @newrelic/gatsby-theme-newrelic. In your local version of this repository, you can run:

cd gatsby-theme-newrelic
cd packages/gatsby-theme-newrelic
yarn
yarn link

Then, within the the repository you would like to see the changes, you can link to this version. For example, if you would like to see the changes in your local version of newrelic/docs-website.

cd docs-website
yarn link "@newrelic/gatsby-theme-newrelic"
yarn
yarn start

If you would like to stop using your local version and instead use the published version, you can remove the symlink from the package.

cd gatsby-theme-newrelic
cd packages/gatsby-theme-newrelic
yarn unlink

Lastly, you can unlink the package from the repository in which you are testing your changes.

cd docs-website
yarn unlink "@newrelic/gatsby-theme-newrelic"

Editing Content

We use MDX files for content which lets you seamlessly write JSX in your Markdown documents. This means you can write content in regular Markdown format as well as including React componenets in the same file. Gatsby will then do all the heavy-lifting to convert these to HTML to serve in the browser.

Example

For this example we will show how to add some content to a page and see the render results in the browser. We will use the build-hello-world-app document for testing, so with the develop server still running, navigate to and open the following in your favourite code editor:

• demo/src/content/build-apps/build-hello-world-app.mdx

You should see something like the following (possibly less wine coloured):

1. Frontmatter - This is key/value metadata you can provide for Gatsby which we won't go into now, but you can read more about here
2. Markdown - This is regular Markdown language, and we'll include a guide on writing Markdown as well as a great resource for practicing online
3. JSX/Components - These are the React components to super-charge your content, you can see the full list of components included in the theme here

Add some Markdown and JSX

Firstly we'll add some standard Markdown to the page, including a Header, bulleted list and link. Feel free to edit the examples:

## My First Edit

Look at me ma i'm creating content for

- New Relic
- Gatsby Theme
- [My inspiration](https://newrelic.com/)

Next we'll add a Button component that links to a site when you click it:

<Button variant="primary" to="https://newrelic.com/">
  Call Friends
</Button>

Your code should now look something like this...

...and as long as your develop server is still running the page should automatically reload with the new content...

Because we've added a Header, My First Edit should now be included in the On this page section on the right. Fresh! :D

Further Editing

With your new found confidence, check out the full documentation for the theme where you'll find more examples for:

• Configuration
• Components
• MDX Component variants
• Hooks

Testing

We're currently developing this package, and will provide test information as we build out the library.

Upon pushing to the develop branch, a preview on a newrelic.com subdomain will be available here!

Support

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. Like all official New Relic open source projects, there's a related Community topic in the New Relic Support Forum.

Contributing

We encourage your contributions to improve gatsby-theme-newrelic! 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 opensource@newrelic.com.

Ensure your git commits and PRs follow the Conventional Commits for commit guidelines.

License

gatsby-theme-newrelic is licensed under the Apache 2.0 License.

The gatsby-theme-newrelic also uses source code from third-party libraries. You can find full details on which libraries are used and the terms under which they are licensed in the third-party notices document.