Movatterモバイル変換


[0]ホーム

URL:


Skip to content
DEV Community
Log in Create account

DEV Community

Adam Gardner
Adam Gardner

Posted on

     

Automated Markdown Testing: Two Options

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
Enter fullscreen modeExit fullscreen mode

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
Enter fullscreen modeExit fullscreen mode

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
Enter fullscreen modeExit fullscreen mode

I could use thesnippets extension mymkdocs.yaml file:

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

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]
Enter fullscreen modeExit fullscreen mode

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"    ```
Enter fullscreen modeExit fullscreen mode

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!

Top comments(0)

Subscribe
pic
Create template

Templates let you quickly answer FAQs or store snippets for re-use.

Dismiss

Are you sure you want to hide this comment? It will become hidden in your post, but will still be visible via the comment'spermalink.

For further actions, you may consider blocking this person and/orreporting abuse

CNCF Ambassador, DevRel working in Observability. I blog at https://agardner.net and YouTube at https://www.youtube.com/@agardnerit
  • Work
    DevRel @ Dynatrace / CNCF Ambassador
  • Joined

More fromAdam Gardner

DEV Community

We're a place where coders share, stay up-to-date and grow their careers.

Log in Create account

[8]ページ先頭

©2009-2025 Movatter.jp