Nested code blocks in technical documentation

nested-code-blocks.md

Nested code blocks

Nested code blocks clarify technical documentation but rendering them with markdown is tricky.

Overview

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

The following are the main features about GCP documentation that I like:

1. Headings name a procedure.
2. Numerical lists describe the ordered steps of a procedure.
3. Nested code blocks illustrate commands in a step.
4. Nested bullets and/or nested paragraphs add relevant details about a given step.

The important technique is nesting. When you nest your steps, commands, and details you organize complicated procedures as clear and manageable chunks. But problems arise when combining numerical lists, bulleted lists, code blocks, and paragraphs. The key technique is: use 3 spaces of indentation and code fences.

GCP example

Consider the following example from the Using Pub/Sub with Cloud Run tutorial:

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.

2. 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.

3. 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:

   1. $CLUSTER_NAME with the name you used for your cluster
   2. $REGION with the supported cluster location of your choice

Discussion

The procedure is clear and ergonomic for readers for the following reasons:

1. Foremost, the procedure is organized into manageable steps. Sometimes multiple commands belong in one step. The nested code blocks handle the situation fine.
2. Copy and paste is easy. I can select all or double click on a given command to copy and paste into my terminal.
3. There are no additional spaces or comments in the code blocks.
4. The variables are clear.
5. 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.

For details about challenges rendering nested code blocks in Markdown, see Fenced code blocks inside ordered and unordered lists gist comment and CommonMark Spec docs.