Docs on gomarklint

Quick Start

Mon, 01 Jan 0001 00:00:00 +0000

Quick Start#

Install#

Download binary (no Go required):

Download the latest binary for your platform from GitHub Releases.

# macOS (Intel)
tar -xzf gomarklint_Darwin_x86_64.tar.gz
# Linux (x86_64)
tar -xzf gomarklint_Linux_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

Build from source:

Rules

Mon, 01 Jan 0001 00:00:00 +0000

Rules#

gomarklint currently runs the following checks (ordered as executed):

Rule key	What it detects	Notes / Options
`final-blank-line`	Missing final blank line at EOF	Toggle: `--enable-final-blank-line-check` (default on)
`unclosed-code-block`	Unclosed fenced code blocks (```)	Always on
`empty-alt-text`	Image syntax with an empty alt text	Always on
`heading-level`	Invalid heading level progression (e.g., H2 → H4 skip)	Toggle: `--enable-heading-level-check` (default on) / `--min-heading` (default 2)
`duplicate-heading`	Duplicate headings within one file	Toggle: `--enable-duplicate-heading-check` (default on)
`no-multiple-blank-lines`	Multiple consecutive blank lines	Toggle: `--enable-no-multiple-blank-lines-check` (default on)
`external-link`	External links that fail validation	Toggle: `--enable-link-check` (default off). Skips URLs that match `--skip-link-patterns` (regex).
`no-setext-headings`	Setext heading used instead of ATX style	Toggle: `--enable-no-setext-headings-check` (default on)

Execution details#

Files/dirs are expanded with ignore patterns from config.
Per-file issues are sorted by line asc before printing.
Line count is computed as \n count + 1 for reporting.

CLI

Mon, 01 Jan 0001 00:00:00 +0000

CLI#

gomarklint [files or directories] [flags]

If no paths are given, the tool will use include from .gomarklint.json if present, otherwise error out with:

“please provide a markdown file or directory (or set ‘include’ in .gomarklint.json)”

Flags#

Flag	Type	Default	Description
`--config`	string	`.gomarklint.json`	Path to config file.
`--output`	`text` \| `json`	`text`	Output format. Any other value is rejected.
`--severity`	`warning` \| `error`	`warning`	Minimum severity level to include in output (see below).

Severity levels#

Each rule can be configured with a severity of "error" or "warning" in the config file.

Configuration

Mon, 01 Jan 0001 00:00:00 +0000

Configuration#

A JSON config is read from the path given by --config (defaults to .gomarklint.json) if the file exists.

Example#

{
 "default": true,
 "rules": {
 "final-blank-line": true,
 "unclosed-code-block": true,
 "empty-alt-text": true,
 "heading-level": { "severity": "error", "minLevel": 2 },
 "duplicate-heading": true,
 "no-multiple-blank-lines": true,
 "no-setext-headings": "warning",
 "external-link": { "severity": "error", "timeoutSeconds": 5, "skipPatterns": ["^https://localhost"] }
 },
 "include": ["docs", "README.md"],
 "ignore": ["node_modules", "vendor"],
 "output": "text"
}

Top-level fields#

Field	Type	Default	Description
`default`	bool	`true`	Whether unlisted rules are enabled by default (opt-out mode). Set to `false` for opt-in mode.
`rules`	object	all rules enabled as `error`	Per-rule configuration. See Rule values below.
`include`	string[]	`["README.md", "testdata"]`	Paths to lint when no CLI paths are provided.
`ignore`	string[]	`[]`	Path patterns to exclude.
`output`	string	`text`	`text` or `json`.

`default` field#

Controls how rules not listed in rules are treated.

Output

Mon, 01 Jan 0001 00:00:00 +0000

Output#

Human-readable (`--output text`, default)#

❯ gomarklint testdata/sample_links.md

Errors in testdata/sample_links.md:
 testdata/sample_links.md:1: First heading should be level 2 (found level 1)
 testdata/sample_links.md:4: Link unreachable: https://httpstat.us/404
 testdata/sample_links.md:12: Link unreachable: http://localhost-test:3001
 testdata/sample_links.md:16: duplicate heading: "overview"
 testdata/sample_links.md:18: image with empty alt text


✖ 5 issues found
✓ Checked 1 file(s), 19 line(s) in 757ms

Summary: ✖ N issues found if issues, ✔ No issues found if clean.
Prints stats line: Checked <files>, <lines>[, <links>] in <Xms|Ys> (includes link count when link checking is enabled).

JSON (`--output json`)#

{
 "files": 1,
 "lines": 19,
 "errors": 5,
 "elapsed_ms": 790,
 "details": {
 "testdata/sample_links.md": [
 { "File": "testdata/sample_links.md", "Line": 1, "Message": "First heading should be level 2 (found level 1)" },
 { "File": "testdata/sample_links.md", "Line": 4, "Message": "Link unreachable: https://httpstat.us/404" },
 { "File": "testdata/sample_links.md", "Line": 12, "Message": "Link unreachable: http://localhost-test:3001" },
 { "File": "testdata/sample_links.md", "Line": 16, "Message": "duplicate heading: \"overview\"" },
 { "File": "testdata/sample_links.md", "Line": 18, "Message": "image with empty alt text" }
 ]
 }
}

details maps file path → list of issues (file, line, message).
elapsed_ms is total wall time for the run.

Performance

Mon, 01 Jan 0001 00:00:00 +0000

Performance#

gomarklint is built for speed, with optimizations for both file parsing and external link validation.

Structural checks#

Headings, code blocks, blank lines, etc.:

Scanning 185 files and 104,000+ lines takes under 60ms

External link checking (`--enable-link-check`)#

Optimized concurrent validation with intelligent batching
~2,000 external links validated in under 10 seconds
Significantly faster than traditional sequential HTTP checks

Recommended usage#

For rapid local feedback:

Run without --enable-link-check → completes in milliseconds
Perfect for catching structural issues while editing

For comprehensive validation:

GitHub Actions

Mon, 01 Jan 0001 00:00:00 +0000

GitHub Actions Integration#

You can use gomarklint in your CI workflows using the official GitHub Action.

Note: It is recommended that you create a .gomarklint.json configuration file in your repository root before using gomarklint in GitHub Actions. If no configuration file is present, gomarklint will run with its default settings. You can generate a starter config with: gomarklint init

Example: `.github/workflows/lint.yml`#

name: Lint Markdown

on:
 push:
 paths:
 - '**/*.md'
 pull_request:
 paths:
 - '**/*.md'

jobs:
 markdown-lint:
 runs-on: ubuntu-latest
 steps:
 - name: Checkout code
 uses: actions/checkout@v4

 - name: Run gomarklint Action
 uses: shinagawa-web/gomarklint-action@v1

Roadmap

Mon, 01 Jan 0001 00:00:00 +0000

Roadmap (Post v1.0.0)#

Core Quality & Rule Expansion#

max-line-length: Enforce maximum line width
no-multiple-consecutive-blank-lines: Disallow multiple blank lines
image-alt-text improvements: Enforce alt text style and length
Rule severity levels (e.g. warning, error)

Extensibility#

Plugin system for custom rules (via Go interface or external binary)
Allow disabling specific rules via inline comments (e.g. )

Testing & Stability#

Snapshot testing support for easier rule verification
Regression test suite for real-world Markdown samples

Developer UX#

VS Code extension using gomarklint core
Interactive mode (e.g. prompt to fix or explain errors)
File caching for faster repeated linting

Ecosystem & CI#

GitHub Actions integration
Prebuilt binaries via goreleaser (macOS/Linux/Windows)
Homebrew formula
Docker image (e.g. ghcr.io/shinagawa-web/gomarklint)

Internationalization#

Localized messages (e.g. Japanese, Spanish)
Rule messages with IDs and documentation links

Feel free to suggest more ideas by opening an issue or discussion on GitHub!

Migrating to v2

Mon, 01 Jan 0001 00:00:00 +0000

Migrating to v2#

v2 replaces the flat boolean config fields with a unified rules map. This enables per-rule severity levels, rule options, and a much cleaner foundation for adding new rules.

What changed#

Config file format#

{
 "minHeadingLevel": 2,
 "enableLinkCheck": false,
 "linkCheckTimeoutSeconds": 5,
 "skipLinkPatterns": [],
 "enableHeadingLevelCheck": true,
 "enableDuplicateHeadingCheck": true,
 "enableNoMultipleBlankLinesCheck": true,
 "enableNoSetextHeadingsCheck": true,
 "enableFinalBlankLineCheck": true,
 "include": ["README.md", "docs"],
 "ignore": [],
 "output": "text"
}

{
 "default": true,
 "rules": {
 "heading-level": { "enabled": true, "severity": "error", "minLevel": 2 },
 "duplicate-heading": true,
 "no-multiple-blank-lines": true,
 "no-setext-headings": true,
 "final-blank-line": true,
 "unclosed-code-block": true,
 "empty-alt-text": true,
 "external-link": { "enabled": false, "severity": "error", "timeoutSeconds": 5, "skipPatterns": [] }
 },
 "include": ["README.md", "docs"],
 "ignore": [],
 "output": "text"
}

Rule value shorthand#

Each rule entry accepts three forms (bool, string, or object):

Docs on gomarklint

Quick Start

Quick Start#

Install#

Rules

Rules#

Execution details#

CLI

CLI#

Flags#

Severity levels#

Configuration

Configuration#

Example#

Top-level fields#

default field#

Output

Output#

Human-readable (--output text, default)#

JSON (--output json)#

Performance

Performance#

Structural checks#

External link checking (--enable-link-check)#

Recommended usage#

GitHub Actions

GitHub Actions Integration#

Example: .github/workflows/lint.yml#

Roadmap

Roadmap (Post v1.0.0)#

Core Quality & Rule Expansion#

Extensibility#

Testing & Stability#

Developer UX#

Ecosystem & CI#

Internationalization#

Migrating to v2

Migrating to v2#

What changed#

Config file format#

Rule value shorthand#

`default` field#

Human-readable (`--output text`, default)#

JSON (`--output json`)#

External link checking (`--enable-link-check`)#

Example: `.github/workflows/lint.yml`#