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:

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.