Gatsby Theme Newrelic is an open-source Gatsby theme monorepo from New Relic that provides the shared UI, MDX content handling, and site scaffolding used across New Relic's official Gatsby websites.
What is Gatsby Theme Newrelic?
Gatsby Theme Newrelic is a collection of Gatsby themes and packages maintained by New Relic, with the main package published as @newrelic/gatsby-theme-newrelic. It runs on the Gatsby static site framework and manages multiple packages through Yarn workspaces. The theme powers four production New Relic sites: docs.newrelic.com, newrelic.com/instant-observability, developer.newrelic.com, and opensource.newrelic.com. It accepts MDX content files as input and outputs compiled HTML pages styled with New Relic's design system and component library.
Key Features
- MDX content editing — Write content with regular Markdown plus JSX/React components in the same file; Gatsby compiles it to HTML for the browser.
- Component library — Includes reusable React components such as a Button with variants, documented in the theme's package README under
components. - Demo site — Includes a small Gatsby demo site for testing theme changes; it builds in about 30 seconds and serves on localhost:8001.
- Yarn workspaces — Monorepo structure with commands like
yarn startandyarn workspace demo developfor running the demo. - Configuration and hooks — Provides configuration options, MDX component variants, and React hooks, all documented in the theme package.
- Symlink development workflow — Supports
yarn linkso you can test local theme changes against other Gatsby sites like docs-website. - Apache 2.0 license — Open source with a permissive license, plus third-party notices for included libraries.
Who is it for?
- New Relic developers — who build or maintain New Relic's Gatsby sites such as docs, developer, open-source, and instant-observability.
- Gatsby theme developers — who want a real-world example of a production Gatsby theme monorepo with MDX and component libraries.
- Technical content authors — who want to write documentation in MDX and add interactive React components directly in Markdown files.
What can you do with it?
- Site builders: Create a new Gatsby site with New Relic's design system and component library by using the theme as a foundation.
- Content editors: Add buttons, headings, and other React components to Markdown documents without leaving the content file.
- Maintainers: Test theme changes locally with the demo site or by symlinking the theme into another Gatsby repository.
How does it work?
The workflow starts by cloning the repository and running yarn to install dependencies. You can start the demo site with yarn start or yarn workspace demo develop, then edit MDX files in demo/src/content to see live reloads in the browser. To test against an external site, you run yarn link inside the theme package, then yarn link "@newrelic/gatsby-theme-newrelic" in the target site.
FAQ
How do I run the demo site?
Run yarn start or yarn workspace demo develop from the repository root. The demo builds in roughly 30 seconds and is available at localhost:8001 in your browser.
What license does Gatsby Theme Newrelic use?
It is licensed under the Apache 2.0 License, and it includes third-party notices detailing the licenses of any source code from other libraries.
How do I test my local changes against another Gatsby site?
Use yarn link in the theme package, then yarn link "@newrelic/gatsby-theme-newrelic" in the target repository (for example, docs-website). When finished, run yarn unlink in both locations to remove the symlink.
What content format does it support?
The theme supports MDX, which combines regular Markdown with JSX. You can write standard Markdown alongside React components, and Gatsby converts the mix into HTML.
Where can I get help?
New Relic hosts a support forum with a dedicated community topic for this theme. Contributions follow Conventional Commits and require signing a CLA via CLA-Assistant; corporate CLA questions can be emailed to [email protected].
