Edit the docs site structure and nav

This doc contains information and procedures pertaining to the structure of the docs site, including: the nav files, the sidebar, the folder or file structure, and more.

For brief instructions for common use cases, see Procedures, but if you're doing larger docs site projects, it's recommended you understand the general concepts beforehand.

Terms

When talking about the docs site structure, sometimes people use different words for the same things. Below is a list of terms that can help us communicate about the docs site structure:

• Doc files: All the docs are represented by .mdx files, also known as markdown files.
• Nav files: The nav files are what govern the displayed structure of the docs site, as exposed in the docs site left sidebar. The nav files are yaml files located in the src/nav directory.
• Folder: In this context, "folders" refers to the actual docs site folder structure (those folders and files in the content directory). Referring to "folders" can be a helpful way to differentiate between the actual folder structure and the displayed structure that's set using the nav files.
• Sidebar: On public-facing docs, the sidebar is what is visible on the left hand side, showing the structure of that category of docs. The sidebar structure is determined by the structure set in the nav file.
• Category or sub-category: we use these words fairly interchangeably to refer to specific areas of the docs site. For example, we might refer to the "Accounts" category, or the "Manage data" category.
• Auto-index pages (deprecated): This refers to a previous implementation where users could load views of the docs in a specific category (for example, by clicking a category heading in the sidebar). We no longer support this implementation.

Understand how the docs site structure works

This section will explain some of the logic behind how the docs site structure is determined and how the structure we display to the public relates to the actual folder structure.

How is the displayed structure related to the actual folders?

The actual docs folder structure (the folders and mdx files in the content folder) is entirely separate from the docs site structure in the sidebar. The displayed structure seen in the sidebar is determined solely by the nav files (the yaml-format files in the src/nav folder).

It's important to understand the above point. The divergence of the docs folder structure and the displayed docs site structure is necessary: we need a way to control the structure displayed in the sidebar without requiring us to keep the folder structure and folder names and doc file names completely equivalent. Because these two things are separate, this can mean that there can be some unintuitive aspects of how that logic works.

We do have procedures for common use cases, but it will help you a lot to understand the specifics below of how the displayed structure is generated.

What determines a doc's URL?

Where a doc file (mdx file) is located in the content folder, and the associated folder and file names, are the only factors that govern that doc's URL.

For example, consider the following doc file automated-user-provisioning-single-sign.mdx:

This doc's URL is solely based on its folder location and the names of the folders. In this case, its URL is:

docs.newrelic.com/docs/accounts/accounts/automated-user-management/automated-user-provisioning-single-sign

This has important implications, including:

• When you move a doc from one folder to another, its URL changes. This means that when you move a doc file, you must add a redirect to that doc of its original URL.
• If you rename an mdx file name or a folder name, that changes its URL. This means you must add a redirect to that doc of its original URL.

What does a nav file do?

The nav files are quite simple. A nav file controls the displayed structure of docs you see in the sidebar. Currently there are multiple nav files, one for each major section of docs. For example, there's a nav file for "Accounts", which contains organization- and account-related settings. And there's a nav file for "Infrastructure monitoring."

For more on nav file format, see Nav file format

What governs how a sidebar displays?

As stated above, the sidebar is just one way that the docs site structure (which is governed by the nav files) is exposed.

When a doc is loaded, the docs site searches for that URL across all the nav files. If it finds a match, it displays that nav file in the sidebar with that doc highlighted.

A doc's URL may exist in more than one nav file. Currently, it's a rule that a doc can only be located in one place across all nav files. But we still have some docs that exist in multiple nav files. For those cases, our site attempts to find the appropriate nav file by choosing the nav file that matches the top level category in the doc URL. For example, if a doc with the relative URL /docs/accounts/accounts-billing/account-setup/create-your-new-relic-account was in two nav files, the docs site code would search to see if one of the nav files has docs/accounts as its first path field. If it finds a match, it uses that nav file.

Nav file format

Below is a snippet of the agents.yml nav file. Note that the file has indentation that corresponds to the level of the navigation hierarchy. When making changes or creating a new nav file, be sure to use the existing spacing format.

yml
title: Agents
path: /docs/agents
pages:
  - title: Manage APM agents
    pages:
      - title: Agent data
        pages:
          - title: Real time streaming
            path: /docs/agents/manage-apm-agents/agent-data/real-time-streaming
          - title: Custom instrumentation
            path: /docs/agents/manage-apm-agents/agent-data/custom-instrumentation
          - title: Agent attributes
            path: /docs/agents/manage-apm-agents/agent-data/agent-attributes
          - title: Custom events
            path: /docs/agents/manage-apm-agents/agent-data/collect-custom-events
          - title: Custom metrics
            path: /docs/agents/manage-apm-agents/agent-data/collect-custom-metrics
          - title: Manage errors
            path: /docs/agents/manage-apm-agents/agent-data/manage-errors-apm-collect-ignore-or-mark-expected
          - title: Link Kubernetes
            path: /docs/agents/manage-apm-agents/agent-data/link-your-applications-kubernetes
      - title: App naming
        pages:
          - title: Name your application
            path: /docs/agents/manage-apm-agents/app-naming/name-your-application
          - title: Use multiple names for an app
            path: /docs/agents/manage-apm-agents/app-naming/use-multiple-names-app

Here are important elements of the nav file:

title: Style guide
path: /docs/style-guide

Procedures

Below are instructions for several common procedures. If you're doing a larger docs project, we recommend familiarizing yourself with the general docs site structure concepts.

Procedures include:

• Overview of what a large docs site restructuring involves
• Add a new docs category
• Add a doc to sidebar/nav-file
• Move docs between folders or categories
• Move or delete folders
• Create placeholder docs

Overview of steps for a large docs site restructure project

For some smaller docs site edits, you can sometimes simply edit the nav files and not have to touch the doc files or folders. But for larger projects, you may want to or need to edit and move the docs files and folders themselves. Below is a broad overview of the chunks of work such larger projects generally entail.

1. Plan out what the new nav file structure will look like, and plan out the work of moving docs files or creating new folders. It can help to write down the chunks of work a large project will entail.
2. Move the affected doc files to their new folder locations, making sure to add redirects. For more on that, see Move docs between folders.
3. Delete any empty folders.
4. For any folder or file edits you do to the file structure itself (including file or folder renaming, moving files and folders, but not including editing of content or front matter within a doc or nav file), do the same edits to the folders and files in the i18n directory. Not all folders or files will be present in the i18n directory: it only populates an mdx file or an associated folder if that mdx file has been marked for translation.
5. Edit the nav files to reflect the new desired structure and point to the new doc URLs.

For more specific and granular procedures, keep reading.

Add a new category of docs

We'll explain two procedures: adding a sub-category of docs in an existing nav file, and adding an entirely new nav file:

Add a new category to a nav file

To add a new category to a nav file:

1. In an existing nav file, add a new category, represented by its title.
2. Add the docs you want in that section, emulating the format and indenting of other nav files.

To learn more about how this works, see:

• How a doc's sidebar is determined
• How a doc category view is determined

Add a new nav file

Adding an entirely new nav file should be rare and something we only do occasionally during large overhauls of site structure. Adding new nav files should get sign-off from a docs site manager.

To add an entirely new nav file:

1. Copy an existing file nav file, or create a new nav file.
2. Customize the new nav file with the categories and docs you want, using the standard nav file formatting and indenting. For more on structure, see nav format.

Add a doc to sidebar/nav-file

Once you create a doc, you need to place it in a nav file. Do not place a doc in more than one nav file location: if you require a link to a doc from a different category, attempt to place that reference within a relevant doc section.

To add a doc to a nav file:

1. In the nav file location where you want to locate it, add the title (its short title displayed in the sidebar and category views) and the path, which is the doc's URL.
2. Ensure that you've emulated the standard nav file formatting and indenting.

Move docs to other categories

Because the nav file and the actual folder structure aren't connected, there are two different ways to "move docs":

• Move a doc in the nav files: preferred and most common procedure.
• Move a doc between folders: less frequent, mainly when doing larger projects where we want to do a significant overhaul of the docs structure and want to ensure the folder structure doesn't become too divergent from the nav file structure.

Move docs using nav file

Move a doc in the nav file when you want to change where it's visible in the sidebar menus.

To move a doc from one place to another in the nav file:

1. In the first nav file, copy the two rows representing that doc's entry (the title and path lines) and paste that content into the place you want it to live in the new nav file.
2. In the new nav file section, make sure the formatting and indenting match standard nav file structure. See Nav format for more about nav file structure.

Move a doc between folders

Note that moving docs between the folders should be relatively rare. The main reasons to do this are when the folder structure and nav file structure are becoming quite divergent, which can be bad for a couple reasons:

• Too much divergence can create user confusion (for example, when the elements of the folder-based URL are very different than the nav-file-based location) or sub-optimal search engine results.
• Too much divergence can make it harder for us to find and edit docs, so there can be value to keeping things fairly up to date and parallel.

When you move a doc between folders or rename a doc, that changes its URL (for more on why, see Understand structure). Similarly, if you rename a folder, that changes the URL of all docs in that area.

To move a doc between folders:

1. Get the current URL of the doc you want to move and add that URL to its own list of redirects. Tips:
   • One way to do this in VSCode is to right click the file name and click "Get relative path".
   • If you are moving many files, ask the team about our scripts for programmatically adding redirects to an entire doc directory.
   • Be sure that redirect URLs don't have a trailing slash.
2. Move the doc to its new folder location.
3. If that mdx file is present in the i18n directory (which it will be if it's marked for translation), make an equivalent move of that file in the i18n directory.
4. Update nav files with the new URL. Having the correct doc URL in the nav file, and not a redirect, is important. Note that a doc's URL may be in more than one nav file so searching the site for that URL can help.

Move or delete or rename a folder

Sometimes when we are doing a larger restructuring project, we may want to move or delete or rename the actual folders instead of simply editing the nav files. Instructions for this:

1. Because moving a folder or changing its name results in changing all the URLs of docs in that folder, you must first add redirects to the affected docs. You can do this manually (described in step #1 here) or you can use a script the docs team has for bulk-adding redirects to all the docs in a directory.
2. Make the desired edit. For example, move the folder to the new location (dragging and dropping in the Finder window, for example), and/or rename the folder.
3. If the edited folder is present in the i18n directory (which it will be if a doc in that folder has been marked for translation), make an equivalent edit of that folder and its files in the i18n directory. Note: the i18n work is only necessary for movements or renaming of folders or files, not for editing of docs or nav file content.

For deleting folders, you'll want to essentially follow the same steps as above: adding redirects for the mdx files being moved or deleted, then moving or deleting the docs, and then deleting the empty folders.

Change a doc's file name

Changing an mdx file's name results in its URL changing. Note that you can change a doc's displayed title in its front matter without changing the actual file name. Changing the file name can be useful. Instructions:

1. Add a redirect to the doc whose file name you're changing.
2. Change the file's name.
3. If that file is present in the i18n directory (which it will be if that doc has been marked for translation), make an equivalent edit of that file's name in the i18n directory. Note: the i18n work is only necessary for movements or renaming of folders or files, not for editing of docs or nav file content.

Create placeholder docs

We no longer want to have docs in multiple places in the nav files (although we still do have some docs that are like this). If you want a doc to be referenced in more than one location in the nav files, instead attempt to find a place within a doc where it makes sense to reference that doc.

Delete or rename image file

See Delete or rename image file.