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.
팁
Your branching YAML file needs to end with the four-letter .yaml
suffix.
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 insrc/install/YOUR_DIRECTORY_NAME
. - The
agentName
,agentType
,title
, andappInfo
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 aselectedOptions
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.
- Referenced in the YAML by
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.
- This is used to display the dropdown content, as well as content that's shown when the
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.
Field | Description |
---|---|
componentType | Sets the type of content to display. Use |
headingText | Sets the H2 header for the step. |
descriptionText | The content that appears directly after the header. |
inputOptions | The section that points to specific editable lines in the config file. |
label | An input field's label text. |
name | The default value in the input field. |
codeLine | The specific line in the config file that's edited. |
defaultValue | The default value in the config file. |
tooltip | On-hover text that appears on an (i) icon next to the input label text. (optional) |
url | A subfield of |
href | A subfield of |
title | A subfield of |
configFilePath | The relative path to the APM (or other) config file. Typically kept in |
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