Markdown indentation

When you're writing in Markdown, indentation can make your doc source more readable. Indentation can also affect the file's readability when it's rendered in HTML. This doc covers how to handle parent (first-level), child (second-level), and grandchild (third-level) lists. We'll also demonstrate how to insert spaces to incorporate code blocks, images, and nested lists within a set of procedures.

List indentation

Lists are a great way to explain procedures (numbered steps) or simply itemize items (bulleted lists). While single-level lists are pretty straightforward, when you start nesting them, you can run into indentation issues. Take a look at these list topics in this section:

First-level lists (parents)
Indentation for child lists

First-level lists (parents)

For first-level lists introduced by a left-justified introductory sentence, we follow this Markdown standard: left-justify all first-level list items. When you publish your document, the Markdown library will indent the first-level list items for you:

Here is a basic list written as left-justified but indented at the time of publication:
* Item 1
* Item 2

This is rendered like this:

Screenshot showing poor formatting of child bullet list

Indentation for child lists

For child or grandchild lists, insert four spaces (or two, two-space tabs) to precede the bullet point or number. While you can use three spaces to indent child lists, we recommend the four space or two tab method, as they render lists more consistently and are easier to type.

In the sections that follow, you'll see examples of how to indent various child lists.

중요

Do not use two-space indentation for any level of list items. While these work in some contexts, they are not predictable. See our two-space examples.

Four-space indentation for child lists (recommended)

We recommend the following spacing in your Markdown because it uses multiples of two spaces:

1. Item 1
2. Item 2
    * Item 2a
    * Item 2b

The Markdown is rendered like this:

Screenshot showing four-space formatting for child

Problems with two-space indentation for lists

While there are some cases where two-space indentation works, such as indenting images or for parent and child bullet lists, your results for numbered lists and other cases can unpredictable. Here are some examples of two-space indentation of a child list. Note that the Markdown library doesn't indent either of these child lists.

A child bullet list:

1. Item 1
2. Item 2
  * Item 2a
  * Item 2b

Note that it renders the child bullets, but they are not indented:

A child numbered list:

1. Item 1
2. Item 2
  1. Item 2a
  2. Item 2b

Note that the Markdown converter can't tell the indented list is a child:

Screenshot showing poor formatting of child numbered list

Bullets nested in numbered lists

When you nest bulleted lists under number lists, indent each child list by four spaces. Look at this Markdown example where a child bullet under step #4 is only indented two spaces:

The process consists of four activities:
1. Review AQM dashboard and KPI trends: Here you and the stakeholders will look at the AQM KPIs and identify their week over week trends. The team should identify areas where KPIs are not improving and develop strategies to drive improvement.
2. Identify achievements, challenges, and opportunities: Here you and the stakeholders will map the current state of alert quality to business impact, identifying areas where improvement has resulted in better business outcomes and areas where problems are impacting business outcomes.
3. Incident policy review: Using the AQM dashboard, you and the stakeholders will identify the noisiest incident policies. Once identified, those policies should be evaluated as detailed in step 4 below.
4. Alert policy recommendations: In this step, you and the stakeholders will review the noisiest policies using the following criteria:
  * Do the alerts have any business impact?
  * Are the policies properly configured?
    * Are they telling us something about the resource that needs to be fixed?
    * Are the policies necessary? Do they have business impact?
    * Are the thresholds set properly?
5. Technical recommendations: Here, you and the stakeholders will review any technical recommendations, including:
    * Are there application / system problems for engineering to review?
    * Are there poorly constructed policies that need to be fixed?
    * Are there instrumentation gaps?

This Markdown with two-space indentation renders like this:

Screenshot showing two-space nesting problem

Here is the same Markdown content but with four spaces preceding the bullets:

The process consists of four activities:
1. Review AQM dashboard and KPI trends: Here you and the stakeholders will look at the AQM KPIs and identify their week over week trends. The team should identify areas where KPIs are not improving and develop strategies to drive improvement.
2. Identify achievements, challenges, and opportunities: Here you and the stakeholders will map the current state of alert quality to business impact, identifying areas where improvement has resulted in better business outcomes and areas where problems are impacting business outcomes.
3. Incident policy review: Using the AQM dashboard, you and the stakeholders will identify the noisiest incident policies. Once identified, those policies should be evaluated as detailed in step 4 below.
4. Alert policy recommendations: In this step, you and the stakeholders will review the noisiest policies using the following criteria:
    * Do the alerts have any business impact?
    * Are the policies properly configured?
        * Are they telling us something about the resource that needs to be fixed?
        * Are the policies necessary? Do they have business impact?
        * Are the thresholds set properly?
5. Technical recommendations: Here, you and the stakeholders will review any technical recommendations, including:
    * Are there application / system problems for engineering to review?
    * Are there poorly constructed policies that need to be fixed?
    * Are there instrumentation gaps?

The Markdown with four space indentation renders like this:

Indentation of consecutive procedures

Consecutive procedures behave as you might expect in Markdown, as long as they're left-justified. However, when you indent consecutive procedures, such as inside a collapser, Markdown sometimes does some unusual formatting. The following example shows how you'd set up two left-justified, consecutive lists in Markdown (outside of a collapser):

To add or delete tags via the UI:

    1. Select a monitored entity, like a monitored app or host.
    2. Near the entity's name at the top of the page, select the **See metadata and manage tags** menu.
    3. In the menu that pops up, add or delete a tag.
    4. For APM agents, restart your service.

You can also add or delete tags associated with a NRQL alert condition. To add or delete condition tags via the UI:

    1. Navigate to a condition.
    2. Near the condition's name at the top of the form, click **Manage tags**.
    3. In the menu that pops up, add or delete a tag.

However, inside a collapser where you're already indenting the content, Markdown can get confused about how to format the indentations:

Markdown doesn't indent the introductory sentences for the second procedure.
Markdown starts the numbering of the second procedure based on the last number of the first procedure.

Here's an example of how the Markdown for same consecutive procedures are indented inside of a collapser.

<CollapserGroup>
  <Collapser
    id="incorrect-formatting"
    title="Two consecutive lists with incorrect formatting"
  >
    When you add tags via the UI or API, this occurs at the entity level. This means that, for example, if you have multiple APM agents monitoring a single entity and apply a tag via the UI, that tag is available for all data coming from that entity.

    To add or delete tags via the UI:

      1. Select a monitored entity, like a monitored app or host.
      2. Near the entity's name at the top of the page, select the **See metadata and manage tags** menu.
      3. In the menu that pops up, add or delete a tag.
      4. For APM agents, restart your service.

    You can also add or delete tags associated with a NRQL alert condition. To add or delete condition tags via the UI:

      1. Navigate to a condition.
      2. Near the condition's name at the top of the form, click **Manage tags**.
      3. In the menu that pops up, add or delete a tag.

    To manage tags via API: see our [NerdGraph tagging docs](/docs/apis/nerdgraph/examples/nerdgraph-tagging-api-tutorial). For a guide to using our CLI to automate tagging, see [our developer site](https://developer.newrelic.com/automate-workflows/5-mins-tag-resources/).
  </Collapser>
</CollapserGroup>

When the Markdown is rendered, the introduction for the second procedure isn't indented (see "You can also add...") and note how the numbering for the second procedure starts at 5:

Screenshot showing how indentation in collapsers can go wrong

To avoid this unfortunate indentation and numbering, insert a second blank line feed so you have two line feeds separating the introductory sentence of the second procedure from the last numbered item of the first list. Here's how that markup looks:

Screenshot showing where to add extra line feed

Here is how this Markdown is rendered in HTML:

Code snippets in procedures

When you have a code snippet in a numbered list, indent snippets so they match the indentation of their parent steps (typically two spaces). Also, we recommend you use even-numbered indentation (with tabs composed of two spaces) like this:

Here is how this Markdown is rendered:

Image indentation

Images under list items should be indented the same as their parents. This shows the reader that the image is directly tied to that list item. Here's an example where the first image doesn't use the same indentation as the parent list item. The second image is indented correctly:

1. First, New Relic gathers all relevant incidents. This includes incidents where [decision-logic steps 1 and 2](#build-decision) are true, and that are also within the defined time window in advanced settings.

<img
  title="topology-1.png"
  alt="New Relic topology explained 1"
  src="/images/styleguide-Indents-and-Images-Incorrect-Example"
/>

<figcaption>
  In this example, all of the incidents in the dotted-line selection have met these requirements: they've gone through the [decision logic in steps 1 and 2](#build-decision), and all contextual comparisons made in [decision logic step 2](#build-decision) are true.
</figcaption>

2. Next, we attempt to associate each incident to a vertex in your [topology graph](#create-topology-graph) using a vertex's defining attributes and the available attributes on the incident.

  <img
    title="topology-2.png"
    alt="New Relic topology explained 2"
    src="/images/styleguide-Indents-and-Images-Correct-Example"
  />

  <figcaption>
    Here's an example of the steps for associating incidents with the information in the topology graph.
  </figcaption>

Here is how it is rendered. Note that the first image should have been indented under the step:

Screenshot showing indentation for images

List indentation .css-21sua1{background:none;border:none;width:0;padding:0;}