DEV Community: Kazu

I Built a Markdown Linter in Go — Here's How It Stacks Up Against markdownlint and remark-lint

Kazu — Tue, 10 Mar 2026 13:00:00 +0000

Documentation breaks quietly. Trust erodes loudly.

If you've worked on an engineering team with shared documentation, you've probably seen this:

An H4 heading appearing directly under an H2 with no H3 in between
A [see details](#overview) link silently 404ing because someone renamed the section
A fenced code block missing its closing backticks — making everything below it render as code

Unlike code bugs, documentation quality degrades without throwing errors. By the time someone notices, someone else is already confused.

That frustration led me to build gomarklint — a fast, opinionated Markdown linter written in Go, designed for CI.

Why not just use an existing tool?

That was my first question too.

The existing tools are excellent, but they each have tradeoffs:

markdownlint (JavaScript): Requires Node.js. Adding it to a Go project's CI means pulling in a JS runtime just for linting.
remark-lint (JavaScript): Extremely powerful and pluggable, but configuration complexity can be a barrier.
mdformat (Python): A formatter, not a linter — it silently rewrites files rather than reporting violations.

I wanted something I could drop into any CI pipeline with a single binary, no runtime dependencies. In Go, that's natural.

I did a deep dive into the Markdown linter ecosystem

Before planning gomarklint's next phase, I did a structured comparison of the major tools. Here's what the landscape looks like:

Tool	Language	Stars	Rules	Nature
markdownlint (DavidAnson)	JavaScript	~5,900	60 built-in	Structural linter
remark-lint	JavaScript	~1,000	~80 packages	Structural linter (AST-based)
markdownlint (Ruby)	Ruby	~2,009	~50	Structural linter
mdformat	Python	~726	N/A	Auto-formatter
gomarklint	Go	—	8	Structural linter

I'll be honest: gomarklint currently has 8 rules. Compared to markdownlint's 60, that's a significant gap. But rule count isn't the whole story.

What makes gomarklint different

Digging into how these tools work revealed some genuine differentiators.

1. Live HTTP link validation

gomarklint . --enable-link-check

Neither markdownlint nor remark-lint validates whether external URLs actually resolve. gomarklint makes real HTTP requests and reports unreachable links — with concurrent validation that can check ~2,000 links in under 10 seconds.

This turns out to be a meaningful differentiator. Dead external links are one of the most common ways documentation silently degrades over time.

2. Unclosed code block detection

func main() {
    // This code block was never closed...

Most linters use tolerant AST parsers that silently repair structural errors. gomarklint uses a text-based approach that catches the raw structural breakage — the kind that makes everything below a fence render as a code block.

3. Single static binary — no runtime required

# Download the binary — no Node.js, no Python, no Go needed
tar -xzf gomarklint_Darwin_x86_64.tar.gz
sudo mv gomarklint /usr/local/bin/

No Node.js. No Python. One line and you're ready. This makes CI integration trivially simple, especially for Go projects or polyglot repos where you don't want to manage a JS/Python environment.

4. Frontmatter-aware parsing

gomarklint strips YAML/TOML frontmatter before applying rules, so it works cleanly with Hugo, Jekyll, and other SSG-based documentation setups without false positives.

5. Goroutine-based concurrent processing

185 files, 104,000+ lines — under 60ms

Fast enough to run on every save locally. Practical even at scale in CI.

Where gomarklint stands today

gomarklint's current 8 rules map to well-known equivalents in the ecosystem:

gomarklint Rule	markdownlint	remark-lint
`final-blank-line`	MD047	`final-newline`
`unclosed-code-block`	— (unique)	— (unique)
`empty-alt-text`	MD045	—
`heading-level`	MD001 + MD041	`heading-increment`
`duplicate-heading`	MD024	`no-duplicate-headings`
`no-multiple-blank-lines`	MD012	`no-consecutive-blank-lines`
`external-link`	— (unique)	— (unique)
`no-setext-headings`	MD003	`heading-style`

The two rules with no equivalent — unclosed-code-block and external-link — are where gomarklint offers something the major tools don't.

What's coming next

The gap analysis made the roadmap clear. Here's what I'm planning to add, starting with the highest-impact rules:

Priority 1 — Simple to implement, high real-world value:

Rule	Description
`fenced-code-language`	Fenced code blocks must specify a language
`single-h1`	Only one H1 heading per document
`blanks-around-headings`	Headings must be surrounded by blank lines
`no-bare-urls`	URLs must use proper Markdown link syntax
`no-trailing-spaces`	No trailing whitespace at end of lines
`no-emphasis-as-heading`	Bold/italic text must not substitute for headings
`no-empty-links`	Links must not have an empty destination
`blanks-around-lists`	Lists must be surrounded by blank lines

Each rule will be designed with the same pattern: a toggle flag, a config field, unit tests, a benchmark, and documentation. No shortcuts.

The full gap analysis and planned rule set is tracked in Issue #76.

Try it

go install github.com/shinagawa-web/gomarklint@latest
gomarklint init
gomarklint .

Full documentation: https://shinagawa-web.github.io/gomarklint/

If you try it and hit an edge case, open an issue. If you want to contribute a rule, PRs are very welcome. The codebase is small and the patterns are consistent — a new rule is typically 50–100 lines of Go plus tests.

Docs break quietly. Let's make them break loudly — in CI, before they ship.

Beyond Lines: Announcing "gosemdiff" – A Logic-Aware Diff Tool for Go

Kazu — Fri, 13 Feb 2026 14:50:00 +0000

Today marks a personal milestone: I have finally finished a massive, six-month-long refactoring of my other project, gomarklint.

After spending half a year staring at Go code structures and AST nodes, I realized something painful. Our current tools are still "dumb" when it comes to understanding the intent of our changes. We are still reviewing code line-by-line, even though we think in structures and logic.

That’s why I’m excited to announce my next OSS project: gosemdiff.

The Problem with Current Solutions (Including AI)

We now have AI tools that can summarize Pull Requests for us. They are helpful, but let's be honest: AI summaries are often "vibes-based." An AI might say, "This PR refactors the processing logic," but it can't mathematically guarantee that the logic remains unchanged. AI can hallucinate, overlook edge cases, or fail to distinguish between a variable rename and a subtle logic bug.

As engineers, we don't need a "guess." We need proof.

Standard git diff treats code as text. But code is not just text; it’s a tree of logic.

The Solution: gosemdiff

gosemdiff is a semantic diff tool designed specifically for Go. Instead of comparing lines, it parses your source code into an Abstract Syntax Tree (AST) and compares the underlying structures.

The goal is to provide a "Truth Machine" for your Pull Requests.

Key Concepts:

Semantic Labeling: Automatically identify changes as MOVE, RENAME, or LOGIC CHANGE.
Logic Integrity: Prove that a refactor hasn't changed the execution flow by comparing normalized AST hashes.
Test-Gap Detection: Alert you if a logic change was made without any corresponding updates to your *_test.go files.
Zero-Noise Mode: Completely ignore comments, formatting, and import ordering.

The Roadmap to v1.0.0

I’ve laid out an ambitious roadmap in the repository, moving from basic function inventorying to a fully integrated GitHub Action.

The ultimate goal? A CI bot that tells your reviewers:

"This PR is 90% refactoring. Logic changes detected in only 2 files. One logic change is missing a unit test."

I Need Your Feedback!

I’m taking a short break to recharge after the gomarklint marathon, and full-scale development on gosemdiff will kick off in about two months.

However, the "Grand Vision" is already live in the README. I want to build this for the community, so I need your input:

What kind of diffs annoy you the most during code reviews?
What "semantic" features would make your life easier?
What’s your dream CI summary?

Please check out the repo and leave your ideas, feature requests, or "what-ifs" in the GitHub Issues!

👉 gosemdiff

Let's make code reviews about logic again, not just lines.

Making Parallel HTTP Requests Stable in Go: Lessons from Building a Markdown Linter

Kazu — Thu, 15 Jan 2026 13:28:45 +0000

When building gomarklint, a Go-based Markdown linter, I faced a challenge: checking 100,000+ lines of documentation for broken links. Parallelizing this with Goroutines seemed like a "no-brainer," but it immediately led to Flaky Tests in CI environments.

Speed is easy in Go; stability is the real challenge. Here are the three patterns I implemented to achieve both.

The Cache: Preventing 'Barrages'

In a large docset, the same URL appears dozens of times. Naive concurrency sends a request for every single occurrence, which looks like a DoS attack to the host.

Using sync.Map, I implemented a simple URL cache to ensure each unique URL is only checked once.

var urlCache sync.Map

// Check if we've seen this URL before
if val, ok := urlCache.Load(url); ok {
    return val.(*checkResult), nil
}

The Semaphore: Respecting Resource Limits

Even with a cache, checking 1,000 unique URLs simultaneously can exhaust local file descriptors or trigger rate limits.
I used a buffered channel as a semaphore to cap the number of active Goroutines.

maxConcurrency := 10
sem := make(chan struct{}, maxConcurrency)

for _, url := range urls {
    sem <- struct{}{} // Acquire token
    go func(u string) {
        defer func() { <-sem }() // Release token
        checkURL(u)
    }(url)
}

The Retry: Tolerating Network 'Whims'

Networks are inherently unreliable. A momentary blip shouldn't fail your entire CI build. I implemented Exponential Backoff to distinguish between permanent failures (404) and transient ones (5xx, timeouts).

// Only retry if it's a server error or network timeout
if err != nil || status >= 500 {
    time.Sleep(retryDelay * time.Duration(attempt))
    // retry...
}

The "Negative Caching" Trap

The most elusive bug was caching only the status code. If a request failed with a timeout, I stored status: 0. Subsequent checks retrieved 0 but didn't know an error had occurred, leading to inconsistent logic.

The Fix: Cache the entire result, including the error.

type checkResult struct {
    status int
    err    error
}
// Store the pointer to this struct in your cache

Conclusion: Is it 100% Stable?

Not quite. Even with these, "Cache Stampedes" (multiple Goroutines hitting the same uncached URL at the exact same millisecond) remain a concern.

I'm currently exploring golang.org/x/sync/singleflight to solve this. If you have experience tuning http.Client for massive parallel checks, I'd love to hear your thoughts in the comments or on GitHub!

Super Fast Markdown Linting for Go Developers: Meet gomarklint

Kazu — Tue, 13 Jan 2026 07:49:10 +0000

The "Why" (The Motivation)

Documentation is the heart of any project, but keeping it consistent is a nightmare.

While working on various Go projects, I realized a few things about my workflow:

Context Switching Costs: I love Go's speed and simplicity. Having to install Node.js or Ruby just to run a Markdown linter in a Go project felt "heavy."
CI Fatigue: In large repositories, documentation checks shouldn't take seconds—they should take milliseconds. Every second saved in CI is a win for developer experience.
The "Broken Link" Problem: There’s nothing more embarrassing than shipping a README with dead links. I needed a tool that catches these issues instantly.

I couldn't find a tool that was Go-native, ultra-fast, and zero-config by default, so I decided to build one.

The goal for gomarklint was simple: Make Markdown linting so fast and easy that you never have an excuse to skip it.

Speed Performance

When I say "fast," I mean Go-fast.

In many CI/CD pipelines, linting documentation is often the bottleneck that adds unnecessary seconds (or even minutes) to every PR. gomarklint changes that. By leveraging Go's concurrency and efficient string handling, it delivers near-instant feedback.

The Benchmark: I tested gomarklint against a large documentation set:

Total Files: 180 Markdown files
Total Volume: 100,000+ lines of text
Execution Time: < 50ms

To put that in perspective, 50ms is literally faster than the blink of a human eye. You can run this on every single file save without ever noticing a stutter in your workflow.

By removing the overhead of a virtual machine or a heavy runtime, gomarklint ensures that your documentation quality stays high without sacrificing your velocity.

Key Features

gomarklint doesn't just check syntax; it enforces a logical structure for your documentation. Here are the core rules it handles out of the box:

Heading Hierarchy Enforcement: Ever seen a document jump from an H2 directly to an H4? It breaks the visual flow and accessibility. gomarklint ensures your heading levels follow a strict, logical sequence.
Duplicate Heading Detection: Identical headings in the same file can break anchor links (e.g., #features vs #features-1). We catch these early so your internal navigation never breaks.
Broken Link Checker (Internal & External): This is my favorite. It scans your Markdown for links and validates them. No more 404s for your users when they click on a "Getting Started" guide or an external API reference.
Configuration via JSON: While it works great with zero config, you can easily tweak rules or ignore specific paths using a simple .gomarklint.json file.

Quick Start

# install (choose one)
go install github.com/shinagawa-web/gomarklint@latest

# or clone and build manually
git clone https://github.com/shinagawa-web/gomarklint
cd gomarklint
make build   # or: go build ./cmd/gomarklint

1) Initialize config (optional but recommended)

gomarklint init

This creates .gomarklint.json with sensible defaults:

{
  "include": ["."],
  "ignore": ["node_modules", "vendor"],
  "minHeadingLevel": 2,
  "enableHeadingLevelCheck": true,
  "enableDuplicateHeadingCheck": true,
  "enableLinkCheck": false,
  "skipLinkPatterns": [],
  "outputFormat": "text"
}

You can edit it anytime — CLI flags override config values.

2) Run it

# lint current directory recursively
gomarklint ./...

# lint specific targets
gomarklint docs README.md internal/handbook

What's Next? (Roadmap)

gomarklint is already stable and fast, but I have a clear vision for where it’s headed. I’m actively working on expanding its rule set to cover even more edge cases and best practices.

Here’s what you can expect in the coming updates:

max-line-length Enforcement: To keep your Markdown source files readable in any editor or GitHub's UI.
Image Alt-Text Validation: Improving accessibility by ensuring every image has a descriptive alt attribute.
Custom Rules via JSON: Giving you the power to define your own project-specific rules in .gomarklint.json.
Auto-fixing (The Dream): While currently focused on linting, I’m exploring ways to automatically fix simple issues like heading level skips.

We are Open for Contributions! If you have a rule in mind that would make your documentation better, or if you find a bug, please open an Issue or a Pull Request on GitHub. I’d love to build the future of this tool together with the community.

Wrap Up

Building gomarklint has been an incredible journey into the world of Go performance and static analysis. It started as a small tool for my own workflow, but I realized that many other developers are likely facing the same "slow linting" frustration.

If you're looking for a way to keep your documentation spotless without adding bloat to your CI/CD, I’d be honored if you gave gomarklint a try.

Check it out on GitHub: shinagawa-web/gomarklint
Give it a ⭐: If you find the project useful, a Star would mean the world to me and helps others discover the tool!

I’m really curious to hear from you: What’s the most annoying thing you’ve encountered with Markdown formatting? Let’s chat in the comments below!

Happy hacking! 🚀

Building a Culture of Documentation Quality in CI/CD

Kazu — Tue, 28 Oct 2025 23:55:59 +0000

Introduction: Documentation as a Cultural Signal

In many engineering teams, documentation is treated as an afterthought—something we write when there is time, if there is time. Code reviews are systematic, CI pipelines are automated, testing culture is discussed and refined. Yet documentation, which shapes how teams share knowledge and coordinate decisions, is often left to individual discipline and goodwill.

But documentation is not just a collection of text files. It is a cultural signal.

How teams write (and maintain) documentation communicates what they value:

Whether knowledge is shared or siloed
Whether onboarding is a guided process or a form of survival
Whether decisions are remembered or rediscovered
Whether the product’s reality matches its documentation—or not

When documentation decays, trust decays with it. And trust is expensive to regain.

The challenge, then, is not simply “writing more documentation,” but building a culture where documentation is treated as a part of the product itself—reviewed, maintained, and continuously improved alongside code.

This is where treating documentation quality as a first-class citizen in CI/CD pipelines becomes transformative.

When Broken Links Become Broken Trust

Documentation is more than a reference—it is a promise.

When we publish architecture diagrams, onboarding guides, operational runbooks, or product specifications, we are making a statement to our teammates:
“This is how the system works. You can rely on this.”

So what happens when a link is broken?
Or when a README references outdated behavior?
Or when a guide includes instructions that no longer reflect reality?

People stop trusting the documentation.

And once trust is gone, even perfectly correct documentation will be questioned.
Teams start asking around instead of reading.
Knowledge becomes interpersonal again.
The organization quietly shifts from a shared knowledge model to a tribal knowledge model.

This has real costs:

Onboarding slows down
Decision-making becomes opaque
Past lessons are lost and re-learned
Review and collaboration rely on memory instead of artifacts

This is why documentation quality is not a matter of neatness.
It is a matter of organizational reliability.

Broken links are not just broken links.
Broken links are broken trust.

Why Documentation is Hard to Keep Healthy

If we agree that documentation matters, the next question is:
Why is it so hard to keep documentation healthy?

Unlike code, documentation often has no single owner.
It sits in a gray area between product, engineering, design, support, and operations.
Everyone uses it.
Everyone benefits from it.
But no one is explicitly responsible for maintaining it.

And unlike code, documentation does not fail loudly.
There is no compiler complaining.
No CI job turning red.
No stack trace when the meaning shifts or when a sentence becomes outdated.

Documentation decays silently.

Because of this, teams tend to rely on good intentions:

“Someone will update it.”
“We’ll fix it during the next sprint.”
“We’ll remember this decision anyway.”

But people don’t remember.
Teams grow. People leave. Systems evolve.

Without intentional mechanisms for maintenance, documentation inevitably drifts away from reality.

The challenge is not that teams don’t care.
The challenge is that documentation lacks the same structural safeguards that protect code quality.

To keep documentation healthy, we need systems—not just effort.

Treat Documentation Like Code: Enter Linting

If documentation decays because it lacks structural safeguards,
then the solution is not “more effort,” but better infrastructure.

We don’t maintain code quality through motivation or goodwill.
We maintain it through systems:

Code reviews
Static analysis
Typed contracts
CI pipelines
Test suites

These mechanisms don’t replace human judgment—they support it.
They make the healthy behavior the default behavior.

We can apply the same thinking to documentation.

If we want our documentation to stay reliable,
we need tools that:

Detect inconsistencies early
Make issues visible, not silent
Encourage correction at the moment of change
Keep shared language stable across contributors

This is where documentation linting comes in.

Linting documentation is not about enforcing perfection.
It’s about protecting shared understanding.

It allows teams to shift from
“we update documentation when we remember”
to
“documentation accuracy is continuously verified.”

Not tighter control.
Just better support for the culture we want to create.

Introducing gomarklint: A Practical Linter for Markdown

When we introduced linting into our documentation workflow, we didn’t want a tool that enforced aesthetics, personal style, or formatting fads.
We wanted something simpler and more fundamental:

A tool that helps teams keep documentation trustworthy.

This led to gomarklint — a Markdown linter designed to protect the structural integrity of documentation, without dictating how people should write.

gomarklint focuses on things that directly affect shared understanding:

Detecting broken or missing links
Ensuring heading levels follow a coherent structure
Highlighting ambiguous references or placeholder text
Surfacing subtle inconsistencies that accumulate over time

In other words, it focuses on the parts of documentation that erode trust when they decay.

It is intentionally minimal:
No heavy configuration
No stylistic judgment
No unnecessary rules

Just the core checks that preserve reliability and continuity across contributors.

This matters because a tool influences culture.
If the tool is heavy, people avoid using it.
If it is lightweight and aligned with purpose, it becomes part of everyday practice.

gomarklint was built to be that kind of tool:
Not restrictive.
Just supportive.
Not opinionated.
Just reliable.

A small guardrail that keeps the path clear.

Repository: https://github.com/shinagawa-web/gomarklint

How Our Review Culture Changed After Adoption

When we added documentation linting to our workflow, the most meaningful change was not the number of issues caught.
It was the shift in how the team talked about documentation.

Before:

Documentation updates were “nice to have”
Reviewers focused almost entirely on code
Outdated sections were noticed only when they caused confusion
Small inconsistencies were tolerated because fixing them felt optional

After introducing gomarklint:

Documentation changes became part of the review conversation
Reviewers felt permission to point out unclear naming, missing references, or outdated instructions
Updating documentation became a natural part of making changes—not an afterthought
The threshold for “good enough” rose, but without adding pressure or judgment

The presence of linting changed the default expectation:
Documentation should reflect reality.

And because the tool handles detection, the emotional weight disappears.
Feedback shifted from:

“Why didn’t you update this?”

“The linter caught this—let’s align it.”

This matters.
Not because it catches errors, but because it reframes ownership:
Documentation is something the team maintains, together.

Not heroic effort.
Not personal responsibility.
Just shared care, supported by lightweight automation.

Conclusion: Documentation Quality is Organizational Health

Documentation is not just a record of what we build.
It is a reflection of how we work.

When documentation is reliable, knowledge is shared.
Onboarding is smooth.
Decisions have continuity.
Teams move with confidence.

When it decays, the opposite happens—slowly, quietly, and expensively.

Treating documentation as part of the product is not about increasing process or control.
It is about supporting the culture we want to have:

A culture where knowledge is shared.
Where change is understood.
Where trust is maintained.

Linting is not the solution by itself.
But it is a small, powerful guardrail—one that keeps our shared understanding aligned with reality.

Documentation quality is not a matter of neatness.
It is a matter of organizational health.

And when we care for it intentionally,
the entire team feels the difference.

If you'd like to explore the tool mentioned in this article:

gomarklint

https://github.com/shinagawa-web/gomarklint

Inside gomarklint: Architecture, Rule Engine, and How to Extend It

Kazu — Mon, 13 Oct 2025 00:00:13 +0000

When I released gomarklint, most people asked the same two questions:
“How does it run so fast?” and “Can I add my own lint rules?”

In this post, we’ll dive into the internals of gomarklint — how it parses Markdown efficiently, how rules are defined and executed, and how you can extend it to fit your own documentation style guide.
If you’re a Go developer interested in building your own linter or contributing to gomarklint, this article is your roadmap inside the engine.

shinagawa-web / gomarklint

A fast and configurable Markdown linter written in Go

gomarklint

English | 日本語

A fast, opinionated Markdown linter for engineering teams. Built in Go, designed for CI.

Download binary (no Go required):

Download the latest binary for your platform from GitHub Releases.

# macOS / Linux
tar -xzf gomarklint_Darwin_x86_64.tar.gz
sudo mv gomarklint /usr/local/bin/
# or install to user-local directory (no sudo required)
mkdir -p ~/.local/bin && mv gomarklint ~/.local/bin/

# Windows (PowerShell)
Expand-Archive -Path gomarklint_Windows_x86_64.zip -DestinationPath "$env:LOCALAPPDATA\Programs\gomarklint"
# Add to PATH (run once)
[Environment]::SetEnvironmentVariable("PATH", $env:PATH + ";$env:LOCALAPPDATA\Programs\gomarklint", "User")

Via go install:

go install github.com/shinagawa-web/gomarklint@latest

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).
Process 100,000+ lines in ~170ms — fast…

View on GitHub

Introduction: Why Architecture Matters

When I released gomarklint, most people asked me the same two questions:

“How does it run so fast?”
“Can I add my own lint rules?”

Speed and simplicity don’t happen by accident — they come from design.
gomarklint was built around three principles:

Performance first: it should scan tens of thousands of lines in milliseconds.
Simplicity: configuration and execution must stay minimal.
Extensibility: rules should be easy to read, add, and maintain.

In this post, I’ll open the hood of gomarklint — showing how it parses Markdown efficiently, how rules are executed, and how you can extend it to match your documentation style guide.

Parsing Markdown Efficiently

At the heart of gomarklint is an extremely lightweight file parser.
It doesn’t try to build a full Markdown AST. Instead, it performs structured text scanning that’s optimized for speed and memory locality.

The typical flow looks like this:

File Discovery: gomarklint walks through your repository recursively, ignoring hidden directories (.git, .vscode) and symbolic links.
Line Reader: files are streamed line-by-line instead of loaded entirely into memory.
Frontmatter Skipping: YAML frontmatters (--- ... ---) are automatically ignored to prevent false positives.
Rule Evaluation: each active rule receives a slice of lines and emits lint errors.

This minimal I/O footprint lets gomarklint handle 50,000+ lines in under 50ms — even on modest CI runners.

The Rule Engine: Anatomy of a Lint Rule

Rules in gomarklint are intentionally simple.
Each rule is just a Go function that accepts file content and returns a list of LintErrors:

type LintError struct {
    File    string
    Line    int
    Message string
}

type RuleFunc func(filePath string, lines []string) []LintError

A small example — detecting duplicate headings:

func CheckDuplicateHeadings(filePath string, lines []string) []LintError {
    seen := make(map[string]int)
    var errs []LintError

    for i, line := range lines {
        if strings.HasPrefix(line, "#") {
            if _, ok := seen[line]; ok {
                errs = append(errs, LintError{
                    File:    filePath,
                    Line:    i + 1,
                    Message: fmt.Sprintf("duplicate heading: %s", line),
                })
            }
            seen[line] = i
        }
    }
    return errs
}

This pattern repeats across all built-in rules — headings, code blocks, blank lines, and more.
gomarklint aggregates rule results concurrently, merges them, sorts by file/line, and prints them in a deterministic order.

Adding Your Own Rules

Creating a custom rule is straightforward.

Create a new file under internal/rule/
Implement your rule function — for example, forbid “TODO” comments:

func NoTODO(filePath string, lines []string) []LintError {
    var errs []LintError
    for i, line := range lines {
        if strings.Contains(line, "TODO") {
            errs = append(errs, LintError{
                File:    filePath,
                Line:    i + 1,
                Message: "found TODO comment",
            })
        }
    }
    return errs
}

var Rules = []RuleFunc{
    CheckDuplicateHeadings,
    NoTODO,
    // ...other rules
}

Rebuild and test:

# Run all tests
go test ./...

# Show CLI help from local source
go run . --help

# Generate a default .gomarklint.json (from your local build)
go run . init

# Lint the included sample files in ./testdata
go run . testdata

You can immediately see your new rule in action.
If it’s useful for others, open a Pull Request — gomarklint’s rule library welcomes contributions.

Configuration and Extensibility

All configuration lives in .gomarklint.json, allowing teams to share consistent rules:

{
  "ignore": ["CHANGELOG.md"],
  "rules": {
    "CheckDuplicateHeadings": true,
    "NoTODO": true,
    "ExternalLinks": false
  }
}

Each rule can be toggled on/off, and some accept parameters (like link checking patterns or minimum heading depth).

Future versions of gomarklint will likely support pluggable external rules, where Go plugins or YAML-based configuration can load custom logic at runtime — without forking the repo.

Lessons from Designing for Extensibility

Building gomarklint taught me that simplicity scales better than abstraction.

Many linters become slower or harder to extend as they grow, because every rule depends on a shared complex framework.
gomarklint took the opposite path — keep each rule isolated, independent, and stateless.

That design choice allowed:

Linear scalability with repository size
Easier testing and debugging
Low entry barrier for contributors

Extensibility doesn’t always mean adding layers.
Sometimes, it’s about not adding them.

Conclusion: Build Your Own Linter, or Improve This One

gomarklint isn’t just a tool — it’s a lightweight foundation for building your own Markdown analysis workflows.

Whether you:

want to enforce internal documentation standards,
prototype your own linter ideas, or
contribute a new rule back to the community —

the architecture is open, simple, and waiting for you.

Repository:

shinagawa-web / gomarklint

A fast and configurable Markdown linter written in Go

gomarklint

English | 日本語

A fast, opinionated Markdown linter for engineering teams. Built in Go, designed for CI.

Download binary (no Go required):

Download the latest binary for your platform from GitHub Releases.

# macOS / Linux
tar -xzf gomarklint_Darwin_x86_64.tar.gz
sudo mv gomarklint /usr/local/bin/
# or install to user-local directory (no sudo required)
mkdir -p ~/.local/bin && mv gomarklint ~/.local/bin/

# Windows (PowerShell)
Expand-Archive -Path gomarklint_Windows_x86_64.zip -DestinationPath "$env:LOCALAPPDATA\Programs\gomarklint"
# Add to PATH (run once)
[Environment]::SetEnvironmentVariable("PATH", $env:PATH + ";$env:LOCALAPPDATA\Programs\gomarklint", "User")

Via go install:

go install github.com/shinagawa-web/gomarklint@latest

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).
Process 100,000+ lines in ~170ms — fast…

View on GitHub

Inside gomarklint: Building a High-Performance Markdown Linter in Go

Kazu — Sat, 09 Aug 2025 03:56:27 +0000

shinagawa-web / gomarklint

A fast and configurable Markdown linter written in Go

gomarklint

English | 日本語

A fast, opinionated Markdown linter for engineering teams. Built in Go, designed for CI.

Download binary (no Go required):

Download the latest binary for your platform from GitHub Releases.

# macOS / Linux
tar -xzf gomarklint_Darwin_x86_64.tar.gz
sudo mv gomarklint /usr/local/bin/
# or install to user-local directory (no sudo required)
mkdir -p ~/.local/bin && mv gomarklint ~/.local/bin/

# Windows (PowerShell)
Expand-Archive -Path gomarklint_Windows_x86_64.zip -DestinationPath "$env:LOCALAPPDATA\Programs\gomarklint"
# Add to PATH (run once)
[Environment]::SetEnvironmentVariable("PATH", $env:PATH + ";$env:LOCALAPPDATA\Programs\gomarklint", "User")

Via go install:

go install github.com/shinagawa-web/gomarklint@latest

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).
Process 100,000+ lines in ~170ms — fast…

View on GitHub

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

English | 日本語

A fast, opinionated Markdown linter for engineering teams. Built in Go, designed for CI.

Download binary (no Go required):

Download the latest binary for your platform from GitHub Releases.

# macOS / Linux
tar -xzf gomarklint_Darwin_x86_64.tar.gz
sudo mv gomarklint /usr/local/bin/
# or install to user-local directory (no sudo required)
mkdir -p ~/.local/bin && mv gomarklint ~/.local/bin/

# Windows (PowerShell)
Expand-Archive -Path gomarklint_Windows_x86_64.zip -DestinationPath "$env:LOCALAPPDATA\Programs\gomarklint"
# Add to PATH (run once)
[Environment]::SetEnvironmentVariable("PATH", $env:PATH + ";$env:LOCALAPPDATA\Programs\gomarklint", "User")

Via go install:

go install github.com/shinagawa-web/gomarklint@latest

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).
Process 100,000+ lines in ~170ms — fast…

View on GitHub

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.