Branch install component reference

This is a reference for the components that make up our branched install component.

To get started with the branched install, see Get started with branched install.

The branched install docs are controlled by a configuration YAML file that maps out the relationships between different options. The YAML outlines when and how the pieces of content (located in .mdx files) populate the doc. As users make option selections, the YAML swaps those snippets in and out.

Components

To see the branched install component in action, see our branched install implementations. The main components are:

• Option selection boxes (sometimes referred to as "tile dropdowns") where the choices a user makes dictates what content is displayed
• Numbered steps
• Option for embedded config file that users can input values into
• Installation feedback form (<InstallFeedback />)

How it works

The install docs live in the install directory. There is a single .yaml file that defines how and when specific content is swapped in and out of the doc. The specific pieces of content are represented as .mdx files.

Directory overview

The install framework content lives in src/install.

To create a new install doc, add a directory to install.

Your directory structure needs to look like this:

install
|--assets (used for install images)
|--config (used for the install yaml files)
   |--agent-config (used for the agent config yml files)
|--specific-install (used for a specific install doc)
   |--sub-directory1 (used for .mdx files that will be swapped in)
   |--sub-directory2 (used for .mdx files that will be swapped in)
   |--sub-directoryx (you can have as many sub-directories as you need)

When you start a new branching doc, create a parent directory under the install directory. This is where all of the files for your branching doc live.

The branching YAML file

The branching doc YAML file is a highly customizable way to generate a wide variety of custom, interactive content. Being a YAML file, it's extremely important to pay attention to indents and to make sure that every piece of the YAML file is correct.

When you swap in MDX content in your YAML file, the specific MDX file needs to be local to your install doc directory (for example, Java). Although it might be tempting to link to content anywhere on the docs site for the purposes of reuse, this will cause your doc to break.

Verify YAML script

Given how easy it is to break any YAML file, our helpful engineering team has created a useful script to check for common problems you might see in your YAML file.

In your terminal, go to the docs-website repo directory and run this command:

yarn verify-install-page YOUR_BRANCHING_DOC_DIRECTORY_NAME

For example, for the Java branching doc, you'd use:

yarn verify-install-page java

because the Java branching doc is located at src/install/java.

This script checks the following in your YAML file:

• The agentName value matches the folder name in src/install/YOUR_DIRECTORY_NAME.
• The agentName, agentType, title, and appInfo fields aren't blank.
• The appInfo placeholder field isn't blank.
• The step and overrides file paths are valid paths and point to real files.
• All overrides have a selectedOptions value.
• General YAML syntax issues, such as an extra quotation mark or an invalid indent.

Example YAML files

See Example YAML files.

YAML field name details

• agentName: the directory name where everything lives, also tied to the URL (/install/java)

• title: The name of the doc (same as other .mdx files).

• introFilePath: The file containing the intro content for the doc.

• agentConfigFilePath: (optional, if using a config file) Where the agent config file lives. If it doesn't work, ask eng if it is a supported file type.

• appInfo: The section where your options are defined. Components:

  • optionType: the name you give to a set of options. This name will be referenced in the steps section to dictate what options you're referencing, and also in the associated .mdx file.
  • label: Name for the dropdown, which is displayed above that option box. You can leave this blank, with empty quotes, if you don't want it.
  • placeholder: More text you can put above the option box. You can leave this blank, with empty quotes, if you don't want it.

• options

  • value: The variable for the name for the tile. This is referenced in the steps section when you give the values that govern what files are displayed.
  • displayName: The displayed label of the option tile.
  • logo: Optional. A path to an image used for the option tile.
  • icon: Optional. Use this if you want to use an icon instead of an image (icon name="fe-server”)
  • recommendedGuided: Boolean. This determines whether content in the appInfoConfigOption component type .mdx file will display. This is mostly used for guided install content, but could be used for any content that you want to trigger to display in that file. Read more about guided install options.

• steps: This is the section that determines what content displays. The order these are listed in determines the order of all content.

  • filePath: This is the path to the .mdx file (or theoretical path depending on if it will be triggered).
  • overrides: There are three types of override:
    • Replace. If there is another filePath listed under an override, it means: replace the main file path with this file path depending on the options selected.
    • Display if... This uses the isConditionalStep, which takes a boolean value. This is not an "override," but means: display this file depending on the options selected. For information on using some more complex AND/OR logic, see the Example .NET yaml.
    • Skip. This uses skip, which takes a boolean. This essentially says: display this file but skip it if these options are selected.
  • selectedOptions: The section where you place the relevant option selections. Components include:
    • optionType: this connects to the optionType used in the appInfo section.
    • options
      • value: connects to the value used in the optionType.

Branching MDX files

When working with this install framework, there are specific MDX files to be aware of. The different MDX content types are specified via the componentType frontmatter field.

The different .mdx component types are:

• intro
  • Referenced in the YAML by introFilePath.
  • This is the intro content at the top of the doc.
• default
  • A freeform MDX file.
  • Use this for most of your content.
• appInfoConfigOption
  • This is used to reference option content.
• agentConfig
  • This is used for an agent's config file.

To see examples of MDX files in use, see our Example yaml file.

The agentConfig MDX file

The optional agentConfig MDX file points to the appropriate config file in the install directory and controls which lines in the config file are editable.

---
componentType: agentConfig
headingText: Set your app name and license key
descriptionText: Set your app name and license key. Then download your custom config file.
fileName: newrelic.yml
inputOptions:
  - label: 'Name your app'
    name: appName
    codeLine: 21
    defaultValue: 'My app name'
    toolTip: 'New Relic connects metrics to individual applications using your license key and the primary application name.' 
  - label: 'Enter your license key'
    name: licenseKey
    codeLine: 28
    defaultValue: '12345'
---

When using the config file, we recommend you:

• change the default newrelic.yml permissions to read/write only for the owner of the application server process.
• make sure newrelic.yml is part of your backup routine.
• use the New Relic Diagnostics CLI to validate your settings, either before or after you deploy.

MDX frontmatter fields

• componentType: (use one of these four options) if missing, defaults to “default” type
  • default: free mdx file
  • appInfoConfigOption: this is for dropdowns, use whenever you want dropdowns
  • agentConfig: this if for the yaml file
  • appInfoConfig: this step is the one where you display the content (includes recommendedGuided content)
• descriptionText: The first text in the step content (smaller grey text that acts as a second heading)
• optionType: only added for appInfoConfigOption

What's next section

whatsNextFilePath: This must be in your current directory.