Related Tools

md-go-validator

md-go-validator validates code blocks in Markdown and MDX files. It ensures code examples in your documentation are syntactically valid.

Why It Complements gogenfilter

Tool	What It Does	Scope
gogenfilter	Detects and filters auto-generated Go source files	Production code
md-go-validator	Validates code blocks in documentation files	Documentation

Use them together to keep both your codebase and documentation healthy.

Supported Languages

md-go-validator validates code blocks for Go, TypeScript, Rust, Nix, HCL/Terraform, and Templ — all with pure Go, no CGO required.

Installation

go install github.com/larsartmann/md-go-validator@latest

Usage

# Validate all Go code blocks in your docs
md-go-validator docs/

# Validate multiple languages
md-go-validator -l go,typescript,rust docs/

# JSON output for CI integration
md-go-validator -f json -o results.json docs/

CI Integration

Add to your GitHub Actions workflow alongside gogenfilter:

- name: Validate documentation code blocks
  run: |
    go install github.com/larsartmann/md-go-validator@latest
    md-go-validator -f json -o validation-results.json docs/

Skip Directives

For intentionally partial code snippets, place a skip directive before the code block. Available directives:

• < + !-- skip-validate --> — HTML comment before the code fence
• < + !-- skip-md-validate --> — alternative HTML comment
• < + !-- md-skip --> — short form
• < + !-- no-validate --> — generic form
• // + skip-validate — inline, inside the code block
• // + nolint — familiar linter directive

Library Usage

Use md-go-validator as a Go library for custom tooling:

package main

import (
    "context"
    "fmt"

    mdgovalidator "github.com/larsartmann/md-go-validator/pkg"
    "github.com/larsartmann/md-go-validator/pkg/languages"
)

func main() {
    validator := mdgovalidator.New(true).
        WithLanguages([]languages.Language{
            languages.LangGo,
            languages.LangTypeScript,
        })

    results, err := validator.ValidateFile(context.Background(), "README.md")
    if err != nil {
        panic(err)
    }

    for _, r := range results {
        if r.HasError() {
            fmt.Printf("Error at line %s: %v\n", r.LineNumber, r.Error)
        }
    }
}