gomarklint#

Test codecov Go Report Card Go Reference License: MIT

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

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).

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#

  • ⚡️ Blazingly fast: Process 100,000+ lines in ~170ms (structural checks only, M4 Mac)
  • 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

Planned:

  • Severity levels per rule
  • Customizable rule enable/disable
  • VS Code extension for in-editor feedback