How to create a branching doc from scratch

Branching docs are a powerful tool to offer different paths through our documentation, depending on what options users choose. In the past, we might have represented these choices as a table or a set of collapsers. This new doc format is a flexible and extensible tool that we can use to consolidate our installation docs and innovate on how we present information across our site.

These branching docs are controlled by a configuration YAML file that maps out the relationships between different options. The YAML outlines when and how small snippets of information (contained in individual .mdx files) populate the page. As users respond to prompts, the YAML swaps those snippets in and out.

New components

The branching doc introduces some new components. Some of these components are available for use across the docs site, whether it's a branching doc or not.

The new universal components are:

• installation-specific feedback form
• tab switcher

The branching-specific components are:

• dropdown menus with image-based tile selection
• numbered steps with related titles
• embedded, customizable config text file that can be copied or downloaded

Installation feedback form

To add the installation feedback form to your doc, add the following tag wherever you'd like it to appear:

<InstallFeedback />

Tab switcher

The tab switcher, like collapsers, is a React component that presents an alternate set of content in a single location.

<Tabs>
    <TabsBar>
        <TabsBarItem id=""></TabsBarItem>
        <TabsBarItem id=""></TabsBarItem>
        <TabsBarItem id=""></TabsBarItem>
    </TabsBar>

    <TabsPages>
        <TabsPageItem id="">
        </TabsPageItem>
        <TabsPageItem id="">
        </TabsPageItem>
        <TabsPageItem id="">
        </TabsPageItem>
    </TabsPages>
</Tabs>

Tile dropdown

The tile dropdown is how a reader controls the branching content that's shown on a doc. The dropdown content and structure is controlled via the branching doc's YAML file.

Numbered steps

Nearly every MDX file in a branching doc is represented by a numbered step. The branching doc's numbered steps are automatically generated via the YAML file.

Embedded config file

The APM agent config file is added to the /install/config/agent-config directory. Specific lines can be targeted in the config file for update by the reader.

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.

A sample YAML file

This is a sample YAML file. You can find definitions of these fields in the next section.

agentName: pasta
 agentType: APM
 title: 'How to cook some great pasta'
 metaDescription: "All about making pasta."
 introFilePath: 'src/install/pasta/intro.mdx'
 agentConfigFilePath: 'src/install/config/agent-config/java-newrelic.yml'
 appInfo: 
   - optionType: diet
     label: 'What is your dietary preference?'
     placeholder: 'I eat...'
     options: 
       - value: 'omni'
         displayName: 'everything!'
         logo: 'docker'
       - value: 'vegan'
         displayName: 'everything but animal products'
         logo: 'glassfish'

 steps:
   - filePath: 'src/install/pasta/appInfo.mdx' 
   - filePath: 'src/install/pasta/boil.mdx'
   - filePath: 'src/install/pasta/agentConfig.mdx'
   - filePath: 'src/install/pasta/type/default.mdx'
     overrides: 
       - filePath: 'src/install/pasta/type/omni.mdx'
         selectedOptions: 
           - optionType: diet
             options: 
               - value: 'omni'
       - filePath: 'src/install/pasta/type/vegan.mdx'
         selectedOptions: 
           - optionType: diet
             options: 
               - value: 'vegan'
   - filePath: 'src/install/pasta/sauce.mdx'
 whatsNextFilePath: 'src/install/pasta/whatsNext.mdx'

YAML field name details

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

• title: name of the doc, free text field

• introFilePath: the intro text for the page

• agentConfigFilePath: where the agent yml file lives

• appInfo: where you define the dropdowns

  • optionType: value used for overrides, used for query parameters, also used in places for component type appInfo.mdx, appInfoConfigOption, giving a name to the variable used elsewhere on the page
  • label: name for the dropdown
  • placeholder: text that's there before you selected anything

• options

  • value: the variable for the name for the tile, hooks into the query param for the URL
  • displayName: the label of the tile
  • logo: this is an optional path to an image for the tile
  • icon: use this if you want to use an icon instead of an image (icon name="fe-server”)
  • recommendedGuided: Boolean, determines whether guided install content displays (optional)

• steps: steps section defines all the steps on the page, the order these are listed determines the order of the steps

  • filePath: this is the path to a .mdx file (default file content)
  • overrides: determines if an .mdx file is swapped in
    • skip: Boolean, removes content
    • selectedOptions: this section hooks into the selected values in the app config to replace content
      • optionType: this connects to the appInfo variable name
      • options
        • value: connects to the specific item in a specific dropdown

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 component types are:

• intro
  • Referenced in the YAML by introFilePath.
  • This is the content at the top of the page.
  • Used for intro content.
• default
  • A freeform MDX file.
  • Use this for most of your content.
• appInfo
  • This is used to display the dropdown content, as well as content that's shown when the recommendedGuided: true flag is added to a step.
• appInfoConfigOption
  • This is used to show dropdown content.
• agentConfig
  • This is used to show the APM agent YML config file.

A sample MDX file

--- 
 headingText: Let's begin
 componentType: default
 ---

 Boil your water.

The appInfo MDX file

---
 componentType: appInfoConfig
 headingText: Tell us about your java app
 descriptionText: Select how your app is deployed and your framework. The page updates with the instructions you need for your exact Java setup, so you can start monitoring your app’s performance.
 ---

 ### We recommend the guided install for your app

 A single CLI-command you can run on your system to start monitoring your Java app.
 Java apps deployed via Tomcat, Wildfly/Jboss, and Jetty (standalone).

 <Button variant="primary">Guided Install</Button>

 If you would prefer to install manually you can follow the steps below.

The agentConfig MDX file

The 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: Choose your download option
 descriptionText: Set your app name and license key. Then download your custom config file. You can also use more advanced config setting, see our docs.
 inputOptions: 
   - label: 'Name your app'
     name: "My app name"
     codeLine: 29
     defaultValue: 'My Application'
     toolTip: 'some random info text' 
   - label: 'Enter your '
     url: 
       href: 'http://one.newrelic.com/api-keys'
       title: 'New Relic license key'
     name: licenseKey
     codeLine: 15
     defaultValue: '12345'  
 configFilePath: 'assets/newrelic.yml'
 ---

 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](https://docs.newrelic.com/docs/new-relic-solutions/solve-common-issues/diagnostics-cli-nrdiag/run-diagnostics-cli-nrdiag/) to validate your settings, either before or after you deploy.

MDX frontmatter fields

• headingText: This is the title of the step (required)
• 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

whatsNextFilePath: needs to be in your current directory