Skip Directives

Built-in Directives

Place these before the code block or inside it:

Directive	Format
`<!-- skip-validate -->`	HTML comment
`<!-- skip-md-validate -->`	HTML comment
`<!-- md-skip -->`	HTML comment
`<!-- no-validate -->`	HTML comment
`// skip-validate`	Go comment

Usage

HTML Comment (before the block)

<!-- skip-validate -->

```go
type MyStruct struct {
    Name string
}
```

HTML Comment (inside the block)

```go
<!-- skip-validate -->
type MyStruct struct {
    Name string
}
```

Go Comment (inside the block)

```go
// skip-validate
type MyStruct struct {
    Name string
}
```

Placement Rules

A directive before a block must be a standalone line — prose that merely mentions a directive (e.g. a changelog bullet about a removed //nolint) does not skip the next block. Inside a block, a directive anywhere in the content skips it.

Custom Directives

Define your own skip directives in the config file or via CLI:

md-go-validator --skip-directive "<!-- sketch -->" .

Or in .md-go-validator.yaml:

skipDirectives:
  - "<!-- sketch -->"
  - "<!-- wip -->"

Fail on Skipped

By default, skipped blocks do not cause validation failures. Use --fail-on-skipped to exit 1 if any blocks are skipped:

md-go-validator --fail-on-skipped .

This is useful in strict CI pipelines where all incomplete snippets should be explicitly marked with a meaningful directive.