• Table of Contents
  • 🥞 Stack
    • 🎸 JAMstack
    • 🛠 Tools
    • 🔌 Gatsby plugins
    • 🎨 Gatsby theme
    • 🌐 Hosting and deployment
  • 🖥 Local development
  • 🗂 Directory structure
  • 🤖 Github actions
    • Build and cache site
    • Build with Swiftype content
    • Add slugs to translation queue
    • Send content to be translated
    • Check status of translation jobs
    • Release
    • Sync data dictionary
    • Validate Pull Request
  • ✔️ Content Translation workflow
  • ✨ "Docs as a Service" JSON and XML endpoints
    • Release Notes RSS Feed
    • Security Bulletins RSS Feed
    • What's New RSS Feed
    • What's New NR1 Announcements

At a high level, docs.newrelic.com is built with React and MDX. It uses Gatsby as a static site generator and is hosted on AWS Amplify.

JAM stands for Javascript, APIs & Markup. A core part of the site architecture is Gatsby which is used as a static-site generator. Pages are built by combining Markup (MDX) and Javascript (React) and hosted as static HTML files.

There is no back-end or CMS powering the site.

In addition to the technologies listed above, we use a number of Gatsby plugins. In addition to established third-party plugins, we've also created a few custom plugins to handle specific tasks. For a complete list of plugins, check out our package.json file.

newrelic/gatsby-theme-newrelic

New Relic has developed a Gatsby theme which includes components and configuration shared across several website. The Open Source and Developer site both make use of this theme. For more information on how to use the components and configuration, refer to the README.

The site is currently hosted on AWS Amplify (and is connected to the repository via a webhook). To deploy a new version of the site, simply merge into main (our mainline branch). Amplify will:

1. Build the site by running yarn build:production.
2. If the build succeeds, deploy the new version.
3. If the build fails, do keep the previous version deployed.

Additionally, whenever a pull request is created, a "preview" environment will be spun up. A link for this environment can be found in the "checks" tab for the pull request.

For more information about our CD settings, check out the amplify.yml file. For information about other CI processes, see Github actions below.

To run the project locally, you will need the following dependencies:

• Node 12.x
• Yarn

To get the project running locally, follow these steps:

1. Clone the repository.
2. Install the dependencies by running yarn.
3. Start the development server by running yarn start.

The first time you start the server on a machine, it will take a while to run. Subsequent runs should be faster (Gatsby caching).

For more information, see CONTRIBUTING.md.

Here is a list of the commonly-used directories (see below for a description of each):

.github/workflows/
codemods/
gatsby/
plugins/
rehype-plugins/
scripts/actions/
src/
  | @newrelic/gatsby-theme-newrelic/
  | announcements/
  | components/
  | content/
      | docs/
      | whats-new/
  | data-dictionary/events/
  | data/
  | hooks/
  | i18n/
      | content/
      | nav/
      | translations/
  | layouts/
  | manual-edits/
  | nav/
  | pages/
  | templates/
  | utils/

We use Github actions to perform a number of CI-related tasks. The workflow files are defined via YAML in .github/workflows. Many of them rely on scripts that can be found in scripts/actions/.

NOTE: The translated-related jobs are documented further in an internal document.

Since Amplify does not always accurately communicate the success of PR builds (aws-amplify/amplify-console#550), we run our own build of the site. This will be run when a new pull request is made and is required to pass before new code can be merged into develop.

This will run at regular intervals and gather "related resources" for each page using Swiftype. This is done by running a script (yarn run build:related-content), checking in some additional files, and pushing the new content to main. We have a similar action for the developer website that runs every day.

This action looks at any PR that contains MDX files. If any of the MDX files have translate in frontmatter, it will save the path to the file in a "to be translated" queue. This queue is sent to our translation vendor via another action (see below).

All of the translation-related workflows use AWS DynamoDB to store state between job runs.

This will run at regular intervals and send everything in the "to be translated" queue to our translation vendor. This allows us to batch translation requests rather than sending a new request for every edit.

All of the translation-related workflows use AWS DynamoDB to store state between job runs.

This will run at regular intervals and check if there are any pages that have been successfully translated by our vendor. If any translation jobs are complete, this will pull down the new content, de-serialize it, and create a new pull request with the translated content.

All of the translation-related workflows use AWS DynamoDB to store state between job runs.

Creates a New Relic deployment marker using newrelic/deployment-marker-action.

Syncs the attribute definition data from the repository to the data dictionary service.

Builds the site, runs a test suite, and lints the code. This is run on every pull request and is used as an automated way to check if a pull request is "passing".

Below is a high level explanation of the docs site translation workflow. If you need further details on this flow, and work for New Relic, please contact the Developer Enablement team.

• 😀 A PR is opened with a MDX file that contains a translate flag
• 😀 The PR is merged into the main branch \
  • 🤖 A Github action is run to save the file to a queue
  • 🤖 Once per week, a Github action runs to send the files to our translation vendor
  • 🤖 Once per day, a Github action checks the status of open translation jobs
  • 🤖 If a job is complete, a Github action makes a PR with the new content /
• 😀 The PR is reviewed and merged into main \
  • 🤖 The new translated content is automatically deployed

The Docs site has JSON and XML data endpoints that can be used however you see fit. These endpoints serve up docs content in a standard easy to use format.

All Agents have an XML endpoint that can be used for RSS readers to fetch release notes data.

Example XML endpoint

https://docs.newrelic.com/docs/release-notes/agent-release-notes/{agent_type}/feed.xml

These endpoints can be used to fetch all release notes for an agent type.

All security bulletin content is available in an RSS feed.

https://docs.newrelic.com/docs/security/new-relic-security/security-bulletins/feed.xml

This endpoint can be used to fetch all security bulletins.

All What's New content in src/content/whats-new is available in an RSS feed.

https://docs.newrelic.com/whats-new/feed.xml

What's new announcements highlight new product features in the New Relic One Platform.

https://docs.newrelic.com/api/nr1/content/nr1-announcements.json

This endpoint can be used to fetch the entire NR1 announcement.

https://docs.newrelic.com/api/nr1/content/nr1-announcements/ids.json

This endpoint can be used to fetch just the ID of the NR1 announcement.