Recently I've been writing a lot of tech tutorials at work. These usually comprise of a Markdown file mixed in with code snippets. A user follows the instructions and executes the code snippets at the correct time.

For example:

kind create cluster--config=config.yamlkubectl get namespaces

As I started scaling these tutorials, it became apparently that they could be flaky if / when the underlying technology changed or was updated. Obviously, the problem gets worse the more complexity and piece of tech that are involved in the tutorial.

Option 1: codedown

I need a way to take that Markdown and automatically run the snippets in a "unit test".

One solution is a brilliant, simple project I discovered calledcodedown which extracts the snippet from Markdown.

I can then pipe that to a new file and execute that file as a single e2e test:

cat index.md | codedown shell > e2e.shchmod +x e2e.sh./e2e.sh

Option 2: mkdocs snippets

I write and host the tutorials as Markdown using themkdocs material theme.

An alternative that I'm experimenting with is to keep the entire e2e instructions in a single file, annotating that file in a particular syntax and using the mkdocs snippets extension to include parts of the code at relevant places.

For example, imagine the docs are hosted indocs and this is the e2e shell scriptdocs/e2e/script.sh:

#!/bin/shkind create cluster --config=config.yamlkubectl create namespace fookubectl apply -f ingress.yamlkubectl create namespace barkubectl apply -f app.yaml

I could use thesnippets extension mymkdocs.yaml file:

site_name: An Example Tutorialnav:  - Homepage: index.mdtheme:  name: materialmarkdown_extensions:  - pymdownx.snippets:      base_path: ["docs"]

Then adjustdocs/e2e/script.sh - adding annotations to split into logical sections that I want to include:

#!/bin/sh--8<-- [start:createCluster]kind create cluster --config=config.yaml--8<-- [end:createCluster]--8<-- [start:createFirstNamespace]kubectl create namespace foo--8<-- [end: createFirstNamespace]--8<-- [start:installIngress]kubectl apply -f ingress.yaml--8<-- [end:installIngress]--8<-- [start:createSecondNamespace]kubectl create namespace bar--8<-- [end:createSecondNamespace]--8<-- [start:onboardApp]kubectl apply -f app.yaml--8<-- [end:onboardApp]

In the documentation, simply refer to the snippet names wherever you want to include them:

    ## Time to Spin up the cluster    First, create the cluster:    ```    --8<-- "docs/e2e/script.sh:createCluster"    ```    ## Create First Namespace    Create the first namespace and install the ingress.    ```    --8<-- "docs/e2e/script.sh:createFirstNamespace"    --8<-- "docs/e2e/script.sh:installIngress"    ```

With this method, thee2e.sh script is already ready to run as a single unit.

Summary

I'm still not sure which method I'll end up using, whether I'll find a different way or which is the most scalable (and understandable for other contributors).

I also need to build out the infrastructure to test this (for example when a PR is merged).

Watch this space!