# Nested Code Blocks

> Use nested code blocks for clear technical documentation.

## Overview

Google Cloud Platform (GCP) technical documentation is formatted well enough; however, emulating it with markdown is tricky.

The following are the main features I like:

* Headings name a procdure
* Numbered lists describe steps in a procedure
* Nested code blocks illustrate commands in a given step
* Nested bullets and/or nested paragraphs add important points about a given step

The important technique is: _nesting_. Nesting steps, commands, and details organizes complicated procedures into clear chunks.

## GCP Example

Consider the following example from the [Using Pub/Sub with Cloud Run tutorial](https://cloud.google.com/run/docs/tutorials/pubsub#setting-up-gcloud):

### Setting up gcloud defaults

To configure `gcloud` with defaults for your Cloud Run service:

1. Set your default project:

    ```
    gcloud config set project $PROJECT_ID
    ```

    Replace `$PROJECT_ID` with the name of the project you created for this tutorial.

1. If you are using Cloud Run (fully managed), configure `gcloud` for your chosen region:

    ```
    gcloud config set run/region $REGION
    ```

    Replace `$REGION` with the supported Cloud Run region of your choice.

1. If you are using Cloud Run for Anthos on Google Cloud, configure `gcloud` for your cluster:

    ```
    gcloud config set run/cluster $CLUSTER_NAME
    gcloud config set run/cluster_location $REGION
    ```

    Replace the following:

    * `$CLUSTER_NAME` with the name you used for your cluster
    * `$REGION` with the supported cluster location of your choice

## Discussion

The procedure is clear and ergonomic for readers. I like this format for the following reasons:

* Foremost, the procedure is organized into manageable steps. Sometimes multiple commands belong in one step. The nested code blocks handle the situation fine.
* Copy and paste is easy. I can select all or double click on a given command to copy and paste into my terminal.
* There are no additional spaces or comments in the code blocks.
* The variables are clear.
* The difference between the description of a step, the actual command to run, and important details is clear.

## Implementation

Sadly, this format favors the reader more than the writer. Problems arise when combining numerical lists, bulleted lists, code blocks, and paragraphs. The key technique is: use 4 spaces of indentation and code fences.

Consider this markdown source:

```
1. If you are using Cloud Run (fully managed), configure gcloud for your chosen region:

    ```
    gcloud config set run/region $REGION
    ```

    Replace `$REGION` with the supported Cloud Run region of your choice.

1. If you are using Cloud Run for Anthos on Google Cloud, configure `gcloud` for your cluster:

    ```
    gcloud config set run/cluster $CLUSTER_NAME
    gcloud config set run/cluster_location $REGION
    ```

    Replace the following:

    * `$CLUSTER_NAME` with the name you used for your cluster
    * `$REGION` with the supported cluster location of your choice
```

The following points are important:

* Use the number `1.` for numbered lists because it makes adding new steps easier.
* Use a newline, 4 spaces for indendation, and code fences for nested code blocks.
* Use a newline and 4 spaces for indentation for nested lists and/or paragraphs.