shinagawa-web
/
gomarklint
A fast and configurable Markdown linter written in Go
gomarklint
A fast, opinionated Markdown linter for engineering teams. Built in Go, designed for CI.
- Catch broken links and headings before your docs ship.
- Enforce predictable structure (no more “why is this H4 under H2?”).
- Output that’s friendly for both humans and machines (JSON).
Why
Docs break quietly and trust erodes loudly gomarklint focuses on reproducible rules that prevent “small but costly” failures:
- Heading hierarchies that drift during edits
- Duplicate headings that break anchor links
- Subtle dead links (including internal anchors)
- Large repos where “one-off checks” don’t scale
Goal: treat documentation quality like code quality—fast feedback locally, strict in CI, zero drama.
✨ Features
- Recursive .md search (multi-file & multi-directory)
- Frontmatter-aware parsing (YAML/TOML ignored when needed)
- File name & line number in diagnostics
- Human-readable and JSON outputs
- Fast single-binary CLI (Go), ideal for CI/CD
- Rules with clear rationales (see below)
Planned/ongoing:
- Severity levels per rule
- Customizable rule enable/disable
- VS Code…
Intro
Most Markdown linters focus on correctness, but often at the expense of speed, flexibility, or ease of integration. When you’re working in a large repository with thousands of Markdown files, even a small slowdown in linting can make every CI run feel sluggish.
gomarklint is my answer to that problem — a fast, minimal, CI-friendly Markdown linter written in Go. It checks for common issues like inconsistent heading levels, duplicate headings, unclosed code blocks, and optional external link validation. It’s designed to scan tens of thousands of lines in under 50ms, while staying lightweight enough to configure in seconds.
In this article, we’ll go under the hood of gomarklint: how it’s structured, how it parses Markdown efficiently, how the rules engine works, and which optimizations make it fast. But before we dive into the internals, let’s take a quick look at how to use it.
Quick Start — Using gomarklint
Install
You can install via Go:
go install github.com/shinagawa-web/gomarklint@latest
Initialize Config
This creates a .gomarklint.json file with default rules and file patterns.
gomarklint init
Run Linting
By default, it checks for heading consistency, duplicate headings, unclosed code blocks, and missing trailing blank lines.
gomarklint ./docs
Optional — GitHub Actions Integration
Use the official GitHub Action to run linting automatically on every PR.
Overview of the Architecture
gomarklint’s structure is intentionally simple. The cmd/ package contains the CLI entry point, built with Cobra for easy flag handling. Core logic lives in internal/, which is split into rule/ for linting rules and parser/ for file handling. This separation makes it easy to add new rules without touching CLI code.
Parsing Markdown Files Efficiently
The parser.ExpandPaths() function recursively finds .md files while ignoring hidden directories and symlinks. It also applies include and ignore patterns from the config file. YAML frontmatter is detected and skipped so that headings inside it don’t trigger false positives.
Rule Engine Design
Each rule is a self-contained function that returns a list of LintError structs, each containing the file name, line number, and message. Errors are sorted by line number before output. This keeps the codebase predictable and easy to extend.
Output & CI Integration
gomarklint supports both text and JSON output. JSON mode is especially useful for CI pipelines, where structured output can be parsed by other tools. The program exits with a non-zero status if any errors are found, but only when running in CI (GITHUB_ACTIONS=true), so local runs don’t break your workflow unnecessarily.
Performance Considerations
Because performance was a priority from the start, file reading and rule checks are optimized to minimize allocations. In most cases, link checking is the only operation that significantly impacts runtime, and it’s disabled by default for speed.
Try It on Your Project
If you want to keep your Markdown clean and consistent without slowing down your workflow, try gomarklint today:
Repository:
shinagawa-web
/
gomarklint
A fast and configurable Markdown linter written in Go
gomarklint
A fast, opinionated Markdown linter for engineering teams. Built in Go, designed for CI.
- Catch broken links and headings before your docs ship.
- Enforce predictable structure (no more “why is this H4 under H2?”).
- Output that’s friendly for both humans and machines (JSON).
Why
Docs break quietly and trust erodes loudly gomarklint focuses on reproducible rules that prevent “small but costly” failures:
- Heading hierarchies that drift during edits
- Duplicate headings that break anchor links
- Subtle dead links (including internal anchors)
- Large repos where “one-off checks” don’t scale
Goal: treat documentation quality like code quality—fast feedback locally, strict in CI, zero drama.
✨ Features
- Recursive .md search (multi-file & multi-directory)
- Frontmatter-aware parsing (YAML/TOML ignored when needed)
- File name & line number in diagnostics
- Human-readable and JSON outputs
- Fast single-binary CLI (Go), ideal for CI/CD
- Rules with clear rationales (see below)
Planned/ongoing:
- Severity levels per rule
- Customizable rule enable/disable
- VS Code…
GitHub Action:
https://github.com/marketplace/actions/gomarklint-markdown-linter
Clone the repo, install it, and run gomarklint init — you’ll be linting your docs in under a minute.
Top comments (0)