Nested code blocks in technical documentation

nested-code-blocks.md

Nested code blocks

Nested code blocks organize technical documentation; but rendering them in Markdown is tricky. Luckily GitHub worked around the vague specification by making 4 space indentation "just work".

Overview

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

The following are the main organizational and formatting features about GCP documentation which 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 most important technique is nesting. When you nest your steps, commands, and details, you organize complicated procedures into clear and manageable chunks. But problems arise when combining numerical lists, bulleted lists, code blocks, and paragraphs. The key technique is: use 4 spaces of indentation and code fences.

GCP example

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

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

Rendering nested code blocks in Markdown used to be really difficult; but luckily GitHub worked around the vague specification by making 4 space indentation "just work".

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.