# 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):

### Set 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 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 nested 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 3 spaces of indentation and code fences.