DEV Community: Kazu

grep Said 1,202. The Real Answer Was 10. — Introducing colref

Kazu — Tue, 12 May 2026 23:14:48 +0000

When deleting a database column, I ran grep "\.html\b" across a Django codebase to check for references. It returned 1,202 hits. The column had 10 actual attribute-access references. The other 1,192 were template paths, HTML file extensions in strings, comments, and import fragments — none of which mattered.

Filtering 1,200+ grep hits by hand every time you drop a column isn't a workflow, it's a chore I kept putting off.

So I built colref — a CLI tool that uses AST parsing to find only the attribute-access references to a model field, filtering out everything grep can't.

The Haystack: One Field Name, Ten Thousand Strings

grep treats your codebase as a flat stream of characters. .html matches everything containing those five characters — in code, in strings, in comments, in template paths.

grep -rn "\.html\b" --include="*.py" wagtail/
# 1,202 hits

The 1,192 noise hits in Wagtail break down like this:

Category	Count	Example
HTML file extensions in strings	1,087	`template_name = "pages/publish.html"`
Other string literals	27	`format_html(...)`
Comments	21	`# See docs/settings.html#...`
Other	57	`template_html = base + ".html"`

The same problem appears across every project and every field name. On Mastodon, .domain gives 269 hits; 175 are spec files and SQL heredocs. On Zulip, .name for Stream returns 1,347 hits; 10 are noise.

grep matches characters. It cannot distinguish obj.html from publish.html in a path string.

The Blueprint: AST as a Code Structure Map

colref parses your source files into an Abstract Syntax Tree and walks only the attribute-access nodes — the ones that represent obj.field in running code.

colref check --orm django --model Embed --field html ./wagtail/
# 10 hits

String literals, comments, Django template strings, SQL heredocs, and docstring-embedded code examples are all invisible to the AST walker.

Approach	Hits	What's included
`grep "html"`	3,534	Everything
`grep "\.html\b"`	1,202	File extensions, strings, comments
colref	10	Attribute accesses only

The AST sees obj.html as an attribute access and "publish.html" as a string literal — two different node types.

The Anchor: ORM Schema as a Disambiguation Layer

AST parsing alone is not enough. obj.name might be Stream.name, User.name, or a method call with no relation to your database. colref resolves this by reading the ORM schema first.

For Django, it parses models.py files to find which fields are declared on which model. For Rails, it reads db/schema.rb (or replays migrations if schema.rb is absent). Only references to a field that actually exists on the target model are reported.

colref check --orm rails --model Account --field username ./mastodon/
# 40 hits  (grep \.username\b gives 196)

Without the schema, colref would have no way to distinguish account.username from config.username in a settings file.

The "Implicit Self" Trap

The most common false positive colref produces comes from bare method calls with no explicit receiver:

# Forem — app/views/articles/show.html.erb
<% title "Welcome!" %>
<% title @article.title_with_query_preamble(user_signed_in?) %>

When the field name matches a helper method called on implicit self, colref currently includes it. For the Forem title field, this produced 50 false positives out of 340 reported hits.

The fix is a receiver-aware pass: treat a call node as a candidate only when it has an explicit receiver. That work is on the roadmap.

Verified Against 15+ Real-World Projects

colref has been tested against real OSS codebases across both ORMs:

Django (10 projects: Wagtail, Saleor, Zulip, NetBox, BookWyrm, Misago, django-wiki, and others):

Zero false negatives across all tested model/field pairs
Zero false positives after fixing the models/ package scanner (#65)
Remaining gap: abstract_models.py patterns (django-oscar style) not yet supported

Rails (Mastodon, Forem, Fat Free CRM, Lobsters, Publify, mutual-aid, and others):

Same precision/recall profile
Projects without a committed db/schema.rb now supported via migration replay

Detailed results with TP/FN/FP breakdowns per project are in the GitHub issues.

What's Next

Django and Rails are the first two ORMs. The roadmap includes:

Laravel (PHP) — migration-based schema, Eloquent attribute access
Spring Boot / JPA (Java) — entity annotations, JPA field resolution
Prisma (TypeScript/Node) — schema.prisma as the source of truth

If you use one of these and want to help shape the implementation, the issues are open.

Where it stands

colref filters out the text noise that makes grep unreliable for column reference checks. On Wagtail, Mastodon, and Zulip the signal-to-noise ratio went from roughly 1% to 100%, and I now reach for it before grep when removing a column.

The implicit-self false positives are still there, abstract_models.py isn't handled, and 15 projects is a small slice of the Django and Rails worlds.

If you maintain a Django or Rails codebase, I'd like to know how colref does on your models — especially the cases where it misses something obvious or reports a hit that's clearly noise.

Try it and open an issue if it breaks.

go install github.com/shinagawa-web/colref@latest
colref check --orm django --model YourModel --field your_field ./

👉 github.com/shinagawa-web/colref

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

Kazu — Thu, 30 Apr 2026 05:57:51 +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.

How I Built Inline Disable Comments for a Go Markdown Linter

Kazu — Tue, 28 Apr 2026 13:00:00 +0000

If you've used ESLint, you've probably written // eslint-disable-next-line at least once. It's one of those small features that makes a linter actually usable in the real world — because no rule is right 100% of the time.

I recently built the same feature for gomarklint, a fast Markdown linter written in Go. This post walks through the design decisions and implementation details.

The Problem

gomarklint enforces rules like "no bare URLs," "headings must not skip levels," and "lines must not exceed 120 characters." These rules are useful globally, but sometimes a specific line is legitimately different:

A changelog entry that intentionally contains a bare URL
A generated code block where line length doesn't matter
A one-off exception that would be wrong to suppress project-wide

What we want is a way to suppress violations inline, scoped to exactly the lines that need it — just like markdownlint does with HTML comments:

<!-- markdownlint-disable MD013 -->
A very long line that is intentionally long...
<!-- markdownlint-enable MD013 -->

gomarklint uses the same HTML comment approach, with its own prefix:

<!-- gomarklint-disable MD013 -->

What We Need to Support

There are four directive types, covering both block-level and per-line use cases:

Directive	Scope
`<!-- gomarklint-disable -->`	Disables all rules from this line onward
`<!-- gomarklint-disable MD013 -->`	Disables specific rules from this line onward
`<!-- gomarklint-enable -->`	Re-enables all rules (ends a block disable)
`<!-- gomarklint-enable MD013 -->`	Re-enables specific rules
`<!-- gomarklint-disable-line -->`	Disables all rules on this line only
`<!-- gomarklint-disable-line MD013 -->`	Disables specific rules on this line only
`<!-- gomarklint-disable-next-line -->`	Disables all rules on the next line only
`<!-- gomarklint-disable-next-line MD013 -->`	Disables specific rules on the next line only

The Data Model

The core challenge is representing "which rules are disabled on line N" efficiently. I ended up with three types.

`lineDisable`

This struct describes the disable state for a single line:

type lineDisable struct {
    allDisabled bool
    names       []string
}

The interesting part is that names plays two different roles depending on allDisabled:

If allDisabled is false: names is the list of disabled rules
If allDisabled is true: names is the list of exceptions (rules that are not suppressed)

This lets the same struct handle both "disable everything" and "disable only MD013" without needing separate types. The isRuleDisabled method encodes this logic:

func (ld lineDisable) isRuleDisabled(ruleName string) bool {
    if ld.allDisabled {
        for _, r := range ld.names {
            if r == ruleName {
                return false // explicitly re-enabled
            }
        }
        return true
    }
    for _, r := range ld.names {
        if r == ruleName {
            return true
        }
    }
    return false
}

`disabledSet`

This is just a map from absolute line numbers to their disable state:

type disabledSet map[int]lineDisable

"Absolute line number" matters here because gomarklint strips YAML frontmatter before linting. We need to track an offset so that line numbers stay consistent with what the user sees in their editor.

`blockState`

This tracks the current block-level disable state as we scan through lines:

type blockState struct {
    allDisabled bool
    exceptions  []string // re-enabled rules when allDisabled=true
    rules       []string // named disabled rules when allDisabled=false
}

blockState is a temporary, mutable value — it gets updated as we encounter disable and enable directives, and its current state is applied to each line we visit.

Parsing: Step 1 — Extracting a Directive from a Line

Before we can build the disable map, we need to extract directives from individual lines. parseDirectiveLine handles this:

func parseDirectiveLine(line string) (directive string, ruleNames []string) {
    start := strings.Index(line, "<!--")
    if start == -1 {
        return "", nil
    }
    end := strings.Index(line[start:], "-->")
    if end == -1 {
        return "", nil
    }
    inner := strings.TrimSpace(line[start+4 : start+end])
    const prefix = "gomarklint-"
    if !strings.HasPrefix(inner, prefix) {
        return "", nil
    }
    parts := strings.Fields(inner[len(prefix):])
    if len(parts) == 0 {
        return "", nil
    }
    switch parts[0] {
    case "disable", "enable", "disable-line", "disable-next-line":
        return parts[0], parts[1:]
    default:
        return "", nil
    }
}

Find  to extract the comment body
Check for the gomarklint- prefix
Split the rest into the directive keyword and optional rule names

Rule names are everything after the directive keyword — so  yields ["MD013", "MD032"].

Parsing: Step 2 — Building the `disabledSet`

parseDisableComments scans all lines, maintains a running blockState, and builds the final disabledSet:

func parseDisableComments(lines []string, offset int) disabledSet {
    set := make(disabledSet)
    var bs blockState

    for i, line := range lines {
        absLine := i + 1 + offset
        directive, ruleNames := parseDirectiveLine(line)

        switch directive {
        case "disable":
            if len(ruleNames) == 0 {
                bs = blockState{allDisabled: true}
            } else {
                bs.rules = append(bs.rules, ruleNames...)
            }
        case "enable":
            if len(ruleNames) == 0 {
                bs = blockState{} // full reset
            } else if bs.allDisabled {
                bs.exceptions = append(bs.exceptions, ruleNames...)
            } else {
                bs.rules = removeAll(bs.rules, ruleNames)
            }
        case "disable-line":
            set.addLine(absLine, ruleNames)
        case "disable-next-line":
            if i+1 < len(lines) {
                set.addLine(absLine+1, ruleNames)
            }
        }

        bs.applyTo(set, absLine) // apply current block state to this line
    }

    return set
}

bs.applyTo(set, absLine) is called on every line, not just lines with directives. This is how block-level disabling propagates — the current block state "stamps" each line as we pass it.

disable-line and disable-next-line write directly to set without touching blockState, since they're scoped to one line only.

enable has two behaviors depending on the current block state:

Full enable → reset blockState entirely
Named enable inside an all-disabled block → add to exceptions list
Named enable inside a named-disable block → remove from the rules list

Priority: What Wins When Rules Conflict?

There are cases where a line can be affected by multiple directives. The priority rules are:

All-disabled beats named-disable. If a line is already fully disabled, adding named rules has no effect.
Line-specific directives beat block-level. A disable-line or disable-next-line always takes effect regardless of what the block state says.

addLine enforces rule 1:

func (d disabledSet) addLine(line int, ruleNames []string) {
    existing, exists := d[line]
    if exists && existing.allDisabled && len(existing.names) == 0 {
        return // fully disabled with no exceptions — nothing to add
    }
    if len(ruleNames) == 0 {
        d[line] = lineDisable{allDisabled: true}
        return
    }
    d[line] = lineDisable{names: append(existing.names, ruleNames...)}
}

Integration: Filtering Violations

With the disabledSet built, filtering in collectErrors is a map lookup per violation:

var disabled disabledSet
if strings.Contains(body, "gomarklint-disable") {
    disabled = parseDisableComments(lines, offset)
}

allErrors := l.collectLineErrors(path, lines, offset)
// ... external link checks ...

if len(disabled) > 0 {
    filtered := allErrors[:0]
    for _, e := range allErrors {
        if !disabled.isDisabled(e.Line, e.Rule) {
            filtered = append(filtered, e)
        }
    }
    allErrors = filtered
}

There's a small but meaningful optimization: we only call parseDisableComments if the file body actually contains the string "gomarklint-disable". For files without any directives — the common case — we skip the parsing step entirely. This keeps the hot path fast.

The filter uses the in-place slice trick (filtered := allErrors[:0]) to avoid an extra allocation.

Intentional "Silent Fail" for Invalid Rule Names

What happens if a user writes a typo or a nonexistent rule name?

<!-- gomarklint-disable-line no-bare-url -->
https://example.com

The correct rule name is no-bare-urls (with an s). The result: the directive is silently ignored, and the violation is still reported.

This is intentional. The lookup in isRuleDisabled is a plain string comparison:

for _, r := range ld.names {
    if r == ruleName {
        return true
    }
}

If the name doesn't match any known rule, the function returns false and the violation passes through. There's no registry lookup or error message.

This matches the behavior of markdownlint and most other linters. A warning system for invalid directive names could be added, but for now the behavior is predictable: wrong name → no suppression.

We have explicit E2E tests for this to make sure it stays intentional:

<!-- gomarklint-disable-line no-bare-url -->
https://wrong-rule-name.example.com

<!-- gomarklint-disable-next-line nonexistent-rule -->
https://nonexistent-rule.example.com

Both lines are expected to produce violations — the test fails if they're silently suppressed.

Testing Strategy

The feature is tested at three levels:

Unit tests (disable_comment_test.go) cover parseDirectiveLine and parseDisableComments in isolation — 13+ cases for directive parsing, edge cases for block/line scope interaction, priority rules, and frontmatter offset handling.

Integration tests (linter_test.go) run linter.Run() against in-memory Markdown strings and verify which violations survive filtering. These tests also include a case that confirms parsing is skipped when no directive keyword is present in the file.

E2E tests (e2e_test.go) run the actual binary against a fixture file (disable_comment.md) and check the reported line numbers. This catches any disconnect between the parsing logic and how violations are reported to the user.

The Full Picture

Here's the complete flow, end to end:

Markdown file
    │
    ▼
StripFrontmatter()  →  body string + offset int
    │
    ▼
strings.Contains("gomarklint-disable")?
    │   yes
    ▼
parseDisableComments(lines, offset)
    │   scan each line:
    │     parseDirectiveLine()  →  directive + ruleNames
    │     update blockState
    │     bs.applyTo(set, absLine)
    ▼
disabledSet  (map[int]lineDisable)
    │
    ▼
collectLineErrors()  →  []LintError
    │
    ▼
filter: !disabled.isDisabled(e.Line, e.Rule)
    │
    ▼
sorted []LintError  →  reported to user

The implementation is about 170 lines of Go (internal/linter/disable_comment.go). Most of the logic lives in the data model — the filtering step itself is just a map lookup.

The part I found most interesting was representing "all disabled except these" and "only these are disabled" with the same struct, by flipping what names means depending on allDisabled. It kept the code flat while covering the full directive surface.

Full implementation: gomarklint/internal/linter/disable_comment.go

gomarklint is an open-source Markdown linter written in Go.

How to add a markdown quality gate to your GitHub Actions workflow

Kazu — Tue, 21 Apr 2026 13:00:00 +0000

My team's docs repo crossed 400 files last year. We merged a PR that quietly introduced three broken external links, one heading that jumped from H2 to H4, and a fenced code block without a language tag. None of it failed CI. A reader filed a GitHub issue two weeks later.

Adding a markdown quality gate seemed like an obvious fix, but the first option we tried pulled in a Node.js runtime setup step, a pinned Node version, and a question from a teammate: "why does our docs pipeline touch Node?" This tutorial walks through building a working workflow from scratch — the file path, the triggers, the config, and what a real failure looks like.

Step 1: Create the workflow file

Create .github/workflows/markdown-lint.yml in your repository. Start with just the trigger:

name: Markdown lint

on:
  pull_request:
    paths:
      - "**/*.md"
  push:
    branches:
      - main
    paths:
      - "**/*.md"

The paths filter means the job only runs when a .md file changed. On a busy repo this matters — you don't want a Go or Python change triggering a docs check.

Step 2: Add the job skeleton

Extend the file with a job and the checkout step:

name: Markdown lint

on:
  pull_request:
    paths:
      - "**/*.md"
  push:
    branches:
      - main
    paths:
      - "**/*.md"

jobs:
  lint:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4

Nothing surprising here. Checkout is always first — the linter needs the files on disk.

Step 3: Add the markdown linter to your GitHub Actions job

We'll use gomarklint — a single static binary with no runtime dependencies. The entire lint step is one line:

name: Markdown lint

on:
  pull_request:
    paths:
      - "**/*.md"
  push:
    branches:
      - main
    paths:
      - "**/*.md"

jobs:
  lint:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4

      - name: Lint Markdown
        uses: shinagawa-web/gomarklint-action@v1

That's the complete workflow. Push this file and the markdown lint check will run on every PR that touches a .md file.

Step 4: See a real failure

Without any configuration, gomarklint runs its default rules. A PR that introduces a heading jump produces output like this:

docs/api/endpoints.md:23: heading-level: expected H3, got H4 (skipped a level)
docs/contributing.md:11: fenced-code-language: code block has no language identifier
docs/contributing.md:58: external-link: https://old-domain.example.com/guide returned 404

The job exits non-zero. The PR check goes red. The broken content doesn't merge.

The external link check is the one that would have caught our production issue. gomarklint makes real HTTP requests to each linked URL and reports anything that returns 4xx or 5xx, or times out. No second tool required.

Step 5: Add a config file

Create .gomarklint.yaml at the repo root to tune which rules run and how:

rules:
  heading-level:
    enabled: true
    minLevel: 2
  fenced-code-language:
    enabled: true
  external-link:
    enabled: true
    timeoutSeconds: 10
    skipPatterns:
      - "localhost"
      - "example\\.com"

minLevel: 2 means H1 is reserved for the document title and the linter won't flag its absence in sub-pages. skipPatterns lets you exclude URLs that are intentionally unreachable in CI (local dev URLs, placeholder domains).

The gomarklint action picks up .gomarklint.yaml automatically — no flag needed.

Step 6: Make the markdown lint check block merges

In your repository settings, go to Branches → Branch protection rules → Require status checks to pass before merging and add lint (or whatever you named the job). From this point the check is a hard gate, not advisory.

The full workflow, with config wired in, looks like this:

name: Markdown lint

on:
  pull_request:
    paths:
      - "**/*.md"
  push:
    branches:
      - main
    paths:
      - "**/*.md"

jobs:
  lint:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4

      - name: Lint Markdown
        uses: shinagawa-web/gomarklint-action@v1

The config lives in .gomarklint.yaml at the root. The action finds it automatically.

What the rules actually catch

gomarklint's default rule set covers the problems that consistently show up in team docs repositories:

Heading level jumps (H2 → H4 with no H3)
Duplicate headings within a file
More than one H1 per file
Missing blank lines around headings, lists, and code blocks
Fenced code blocks with no language identifier
Images with missing or empty alt text
Bare URLs that aren't wrapped in link syntax
Empty link destinations
External links that return 4xx/5xx or time out

All rules are on by default and individually toggleable in .gomarklint.yaml.

What it doesn't solve yet

The gate catches structural and link problems reliably. It doesn't enforce prose style — things like passive voice, sentence length, or terminology consistency require a different category of tool. For those, tools like Vale fill the gap, and you can add Vale as a second step in the same job without any conflict.

I'm currently looking at integrating internal anchor validation (catching [see this](#old-anchor) when old-anchor no longer exists after a heading rename). That's the one class of broken link this workflow still misses.

What's the first markdown rule you'd want failing your CI today — structure, links, or something else?

Footnote: why gomarklint over markdownlint-cli2

The other widely-used option is markdownlint-cli2, which has 50+ rules and a large community. The tradeoff is the runtime: it requires a Node.js setup step in CI (~15–20 seconds), which adds friction in non-JavaScript repos.

	markdownlint-cli2	gomarklint
Runtime	Node.js required	None (single binary)
Install in CI	`npm install -g markdownlint-cli2`	GitHub Action or `curl` one-liner
HTTP link validation	Separate tool needed	Built in
Rules	50+	14 structural + link validation

If you already have Node.js in your pipeline, markdownlint-cli2 is a solid choice. If you don't, gomarklint avoids adding it.

→ gomarklint on GitHub
→ gomarklint docs

Shipping a Go CLI to Every Ecosystem: GitHub Releases, Homebrew, and npm

Kazu — Tue, 14 Apr 2026 13:00:00 +0000

The Problem: Great Tools Die in Obscurity

You can build the fastest, most useful CLI tool in the world. But if installing it requires go install, you've already lost 90% of your potential users.

Most developers don't have Go installed. Most frontend engineers don't know what go install means. And most technical writers — the people who benefit most from a Markdown linter — will close the tab the moment they see a compile step.

Distribution is not a feature. Distribution is survival.

This is the story of how I took gomarklint — a Markdown linter written in Go — and made it installable via three ecosystems:

# For anyone — just download and run
curl -L https://github.com/shinagawa-web/gomarklint/releases/latest

# For macOS users
brew install shinagawa-web/tap/gomarklint

# For Node.js users
npm install -g @shinagawa-web/gomarklint

# For Go developers
go install github.com/shinagawa-web/gomarklint@latest

One binary. Four installation methods. Zero runtime dependencies.

Why Multi-Channel Distribution Matters

Let me share a real scenario.

A technical writer on your team wants to lint Markdown docs locally. They open the README, see go install ..., and immediately ask the engineering team for help. The engineer says "just install Go." The writer says "I just want to check my docs." Nothing happens.

Now imagine this instead:

npm install -g @shinagawa-web/gomarklint
gomarklint docs/

Done. No Go. No Homebrew. Just a tool they already know how to use.

Each distribution channel unlocks a different audience:

Channel	Audience
GitHub Releases	CI/CD pipelines, DevOps engineers
Homebrew	macOS developers
npm	Frontend engineers, technical writers
`go install`	Go developers

If your tool only lives in one ecosystem, you're leaving users on the table.

The Architecture: One Binary, Thin Wrappers

The core insight is simple: don't ship your binary inside the package. Download it at install time.

Here's how the npm distribution works:

npm install -g @shinagawa-web/gomarklint
        │
        ▼
  package.json (postinstall → node install.js)
        │
        ▼
  install.js detects OS/arch
        │
        ▼
  Downloads binary from GitHub Releases
        │
        ▼
  Verifies SHA-256 checksum
        │
        ▼
  cli.js (execFileSync → gomarklint binary)

The npm package contains no binary. It's three files:

package.json — metadata and postinstall hook
install.js — platform detection and binary download
cli.js — thin wrapper that invokes the binary

Total package size before install: under 5KB.

Step 1: Platform Detection (install.js)

The install script maps Node.js platform identifiers to GoReleaser archive names:

const PLATFORM_MAP = {
  darwin: "Darwin",
  linux: "Linux",
  win32: "Windows",
};

const ARCH_MAP = {
  x64: "x86_64",
  arm64: "arm64",
};

This covers the six combinations that matter: macOS (Intel + Apple Silicon), Linux (x64 + ARM), and Windows (x64 + ARM).

When npm install runs, the postinstall script:

Reads the version from package.json
Maps process.platform and process.arch to archive names
Downloads the checksums file and the archive in parallel
Verifies the SHA-256 checksum
Extracts the binary with tar
Sets executable permissions

No dependencies. Just Node.js built-ins: https, crypto, child_process, fs.

Step 2: The CLI Wrapper (cli.js)

The wrapper is intentionally minimal:

#!/usr/bin/env node
"use strict";

const { execFileSync } = require("child_process");
const path = require("path");

const ext = process.platform === "win32" ? ".exe" : "";
const bin = path.join(__dirname, "gomarklint" + ext);

try {
  execFileSync(bin, process.argv.slice(2), { stdio: "inherit" });
} catch (e) {
  process.exitCode = e.status || 1;
}

Key design decisions:

stdio: "inherit" — passes through stdin/stdout/stderr, so output formatting and piping work exactly like the native binary
Exit code forwarding — critical for CI usage where non-zero exit means lint failure
No abstraction — the wrapper does nothing but proxy execution

Step 3: Supply Chain Security

Shipping binaries through npm raises legitimate security concerns. Two mechanisms address this:

SHA-256 Checksum Verification

GoReleaser generates a checksums file for every release. The install script downloads it and verifies the archive before extraction:

function verifyChecksum(data, expected) {
  const actual = crypto.createHash("sha256").update(data).digest("hex");
  if (actual !== expected) {
    throw new Error(
      `Checksum mismatch!\n  Expected: ${expected}\n  Actual:   ${actual}`
    );
  }
}

If someone tampers with the binary on GitHub Releases, the install fails loudly.

npm Provenance

The publish step uses --provenance, which cryptographically proves the package was built from a specific GitHub Actions workflow:

- name: Publish to npm
  run: npm publish --provenance --access public
  working-directory: npm
  env:
    NODE_AUTH_TOKEN: ${{ secrets.NPM_TOKEN }}

Users can verify this with npm audit signatures.

Step 4: Automated Publishing with GoReleaser

The entire release pipeline runs on a single trigger: pushing a version tag.

# .github/workflows/goreleaser.yml
on:
  push:
    tags:
      - 'v*'

jobs:
  release:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v6
      - uses: actions/setup-go@v6
      - uses: goreleaser/goreleaser-action@v7
        with:
          args: release --clean

  npm-publish:
    needs: release
    runs-on: ubuntu-latest
    permissions:
      contents: read
      id-token: write
    steps:
      - uses: actions/checkout@v6
      - uses: actions/setup-node@v4
        with:
          node-version: '20'
          registry-url: 'https://registry.npmjs.org'
      - name: Set package version from tag
        working-directory: npm
        run: |
          VERSION="${GITHUB_REF_NAME#v}"
          node -e "
            const fs = require('fs');
            const pkg = JSON.parse(fs.readFileSync('package.json', 'utf8'));
            pkg.version = '${VERSION}';
            fs.writeFileSync('package.json', JSON.stringify(pkg, null, 2) + '\n');
          "
      - name: Publish to npm
        run: npm publish --provenance --access public
        working-directory: npm
        env:
          NODE_AUTH_TOKEN: ${{ secrets.NPM_TOKEN }}

The npm package version is never manually managed. It's extracted from the git tag at publish time. v2.7.1 becomes npm version 2.7.1. Zero version drift.

The npm-publish job has needs: release, so it only runs after GoReleaser has finished uploading all binaries. If GoReleaser fails, npm doesn't publish a broken version.

Step 5: GoReleaser Configuration

One thing I learned the hard way: if you don't explicitly specify architectures, you might be missing builds that your npm users need.

builds:
  - env:
      - CGO_ENABLED=0
    goos:
      - linux
      - windows
      - darwin
    goarch:
      - amd64
      - arm64

Adding explicit arm64 support was essential. Apple Silicon is the default for new Macs, and ARM Linux servers are increasingly common. Without this, npm install would 404 on gomarklint_Darwin_arm64.tar.gz.

Gotcha: The Checksums Filename

Here's something that cost me a failed release.

I assumed GoReleaser generates checksums.txt. It doesn't. It generates gomarklint_2.7.0_checksums.txt — prefixed with the project name and version.

My first npm release failed with:

Error: Download failed: HTTP 404 for
  https://github.com/.../releases/download/v2.7.0/checksums.txt

Always check your actual release assets before writing the download logic:

gh release view v2.7.0 --json assets --jq '.assets[].name'

The Result

One git tag + git push now triggers:

GoReleaser builds binaries for 6 platform/arch combinations
GitHub Release is created with all assets and checksums
Homebrew formula is updated in the tap repository
npm package is published with provenance attestation

Total human effort per release: two commands.

git tag v2.7.1
git push origin v2.7.1

Takeaways

Distribution is a feature. The best CLI tool means nothing if people can't install it.
Don't ship binaries in packages. Download them at install time. Your npm package stays tiny, and you don't need to rebuild for every platform in npm's ecosystem.
Verify everything. SHA-256 checksums and npm provenance are table stakes for binary distribution.
Automate the version. Extract from the git tag. Never manually sync versions across ecosystems.
Test with real installs. npm install -g in a clean environment catches things unit tests never will.

If you're building a Go CLI and only distributing via go install, you're leaving users behind. The npm + Homebrew wrapper pattern takes an afternoon to set up and opens your tool to an entirely new audience.

Try it:

npm install -g @shinagawa-web/gomarklint
gomarklint .

Repository: https://github.com/shinagawa-web/gomarklint
npm: https://www.npmjs.com/package/@shinagawa-web/gomarklint
Documentation: https://shinagawa-web.github.io/gomarklint/

Choosing a Markdown linter for your docs pipeline: what each tool actually covers

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

If you're setting up a documentation quality gate — for a Go service, a platform team's runbooks, or any repo where Markdown is the source of truth — you've probably hit the same decision point: four or five tools come up in search results, they all call themselves "Markdown linters," and it's genuinely unclear what each one actually catches versus what it quietly ignores.

This is a practical breakdown of the major options, what each one covers, where each one stops, and which use case each one fits best.

The tools and what they actually do

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 + link checker

The distinction that matters most isn't language — it's whether the tool reports violations or silently rewrites files. mdformat is an auto-formatter: it won't tell you a heading level is wrong; it will just fix it. If you want visibility into what's broken (for PR review, for CI blocking), you want one of the linters, not a formatter.

If you need the broadest rule coverage: markdownlint

For teams that want thorough enforcement of documentation conventions — heading order, blank lines around elements, consistent list markers, trailing spaces, bare URLs — markdownlint (DavidAnson) is the mature choice. 60 built-in rules, a VS Code extension with wide adoption, and a CLI that integrates into any CI runner.

The cost: it requires Node.js. In a Go or Rust project where you've deliberately kept the toolchain lean, adding a JS runtime just for linting is a real friction point.

Pick this if: your team already runs Node.js in CI, or you need fine-grained rule configuration across many rule categories.

If you need AST-level extensibility: remark-lint

remark-lint operates on the parsed AST rather than raw text, which makes it uniquely suited to writing custom rules that understand document structure — not just surface patterns. Around 80 rules available across packages. The pluggable architecture is its strength; the configuration surface area is also its steepest learning curve.

Pick this if: you need to write project-specific rules, or you're already in the unified/remark ecosystem.

If you need format + dead-link validation in one binary, no runtime: gomarklint

gomarklint is a Go binary with no runtime dependencies. Download it, run it. It covers structural linting and two checks the JS tools don't touch at all:

Live external link validation — most linters ignore whether [see the RFC](https://...) actually resolves. gomarklint makes real HTTP requests, concurrently, and reports 404s and timeouts. ~2,000 links in under 10 seconds.

gomarklint . --enable-link-check

Unclosed code block detection — tolerant AST parsers silently repair a missing closing fence. gomarklint uses a text-based pass that catches the raw break — the one that causes everything below it to render as code.

The tradeoff is honest: 8 rules versus markdownlint's 60. If you need blanks-around-headings, no-bare-urls, or trailing-space enforcement today, gomarklint doesn't have them yet.

Pick this if: your repo is Go or polyglot and you want zero runtime overhead, or dead external links and structural breaks (unclosed fences, heading skips) are your highest-priority catches.

How the rules map across tools

For teams evaluating overlap before switching or combining tools:

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`

unclosed-code-block and external-link have no equivalent in the major JS tools. Everything else in gomarklint's current set has a direct counterpart — so if you're already on markdownlint, you're not losing coverage by keeping it for the rules gomarklint doesn't yet implement.

Quick-reference decision guide

Broadest rule set, VS Code integration → markdownlint (DavidAnson)
Custom rules, AST access → remark-lint
Auto-fix without review → mdformat
No runtime, dead-link detection, CI binary → gomarklint
Maximum coverage today → markdownlint + gomarklint's --enable-link-check as a second pass

Try gomarklint

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

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

Which check has caught the most real issues in your docs pipeline — structural violations like heading order, or dead links that slipped through unnoticed? The answer tends to tell you which tool to reach for first.

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.

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

The Problem with Current Solutions (Including AI)

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

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!

Catch broken links in your Markdown docs before they reach production

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

Your user clicked the "Getting Started" link in your README. They got a 404. You didn't know because the link had been broken for three weeks and no tool in your pipeline caught it.

That's the problem. Dead links in Markdown documentation are silent failures — they don't break tests, don't fail builds, and don't show up in code review. They only surface when a real person hits them.

I built gomarklint to close that gap. Here's what I learned running it across 180 Markdown files totaling 100,000+ lines.

The Three Kinds of Broken Links

Most link checkers treat all links the same. That's a mistake, because internal relative links, external HTTP links, and anchor fragment links fail for completely different reasons.

Internal relative links break when files get moved or renamed during a refactor. A link like [setup](./docs/setup.md) is valid the day you write it and invalid the day someone renames the file without updating references.

External HTTP links break for reasons you don't control — a third-party API changes its URL structure, a service goes down, a library migrates its docs to a new domain. These are often the most embarrassing failures because they affect the first impression a new user has of your project.

Anchor fragment links — links like [see config](#configuration) — break silently when headings change. If someone renames "Configuration" to "Config Options," every anchor pointing to #configuration is now dead, and no compiler will warn you.

gomarklint checks all three categories in a single pass. Enable link checking in your config:

{
  "enableLinkCheck": true,
  "skipLinkPatterns": ["localhost", "example.com"]
}

The skipLinkPatterns field lets you suppress false positives from placeholder URLs without disabling the check entirely.

The CI Hook: Failing the Build Before the PR Merges

Detection only matters if it runs before code ships. A link checker you run manually is a link checker you forget to run.

Here is a complete GitHub Actions workflow that checks every Markdown file on pull requests targeting main:

name: Markdown Link Check

on:
  pull_request:
    branches: [main]

jobs:
  link-check:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4

      - uses: actions/setup-go@v5
        with:
          go-version: "1.22"

      - name: Install gomarklint
        run: go install github.com/shinagawa-web/gomarklint@latest

      - name: Check links
        run: gomarklint --enable-link-check ./...

The total runtime across 180 files is under 50ms — faster than most network round-trips to fetch a single external URL. Because gomarklint is a single compiled binary with no runtime dependency (no Node.js, no Ruby), the only meaningful CI time is the go install step, which caches cleanly via actions/setup-go.

The "Redirect Mask" Trap

The most elusive bug I found during development: external links that return 301 or 302 redirects were being silently treated as valid.

A link to http://old-docs.example.com/api might redirect to https://new-docs.example.com/api today. But in three months the redirect itself is removed, and your link goes from "redirects correctly" to "hard 404" overnight. The link check that passed six months ago is now wrong, and nothing told you the situation changed.

The fix: treat 3xx responses as warnings, not passes. In gomarklint, you can configure followRedirects: false to surface these — which forces you to update the link to the final destination rather than relying on a redirect that may not be permanent.

{
  "enableLinkCheck": true,
  "followRedirects": false
}

This is stricter than most teams want by default, but for docs you intend to maintain for years, it pays off.

What's Not Solved Yet

Link checking against rate-limited external services is still genuinely hard. GitHub, npm, and PyPI all throttle rapid HEAD requests, which produces false 429 failures in CI. The current approach — exponential backoff with a configurable retry count — helps, but a long PR queue can still hit limits.

The approach I'm exploring next is a two-tier strategy: fail the build on internal and anchor-fragment errors (always reliable, zero network cost), and report external link failures as warnings rather than hard errors, so they surface without blocking a merge.

If you've dealt with flaky external link checks in CI — whether in this tool or another — I'd genuinely like to know what threshold or retry logic worked for your repository size.

Check it out on GitHub: shinagawa-web/gomarklint

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

Catch broken links before your readers do.

gomarklint

English | 日本語

Blazing-fast Markdown linter built in Go — 100,000+ lines in ~170ms. Single binary, no Node.js required, and built-in HTTP link validation.

Quick install (macOS / Linux):

curl -fsSL https://raw.githubusercontent.com/shinagawa-web/gomarklint/main/install.sh | sh

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 Homebrew:

brew install shinagawa-web/tap/gomarklint

Via npm:

npm install -g @shinagawa-web/gomarklint

Via go install:

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

100,000+ lines in ~170ms — single binary…

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

Catch broken links before your readers do.

gomarklint

English | 日本語

Blazing-fast Markdown linter built in Go — 100,000+ lines in ~170ms. Single binary, no Node.js required, and built-in HTTP link validation.

Quick install (macOS / Linux):

curl -fsSL https://raw.githubusercontent.com/shinagawa-web/gomarklint/main/install.sh | sh

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 Homebrew:

brew install shinagawa-web/tap/gomarklint

Via npm:

npm install -g @shinagawa-web/gomarklint

Via go install:

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

100,000+ lines in ~170ms — single binary…

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.

DEV Community: Kazu

grep Said 1,202. The Real Answer Was 10. — Introducing colref

The Haystack: One Field Name, Ten Thousand Strings

The Blueprint: AST as a Code Structure Map

The Anchor: ORM Schema as a Disambiguation Layer

The "Implicit Self" Trap

Verified Against 15+ Real-World Projects

What's Next

Where it stands

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

The Problem with Current Solutions (Including AI)

The Solution: gosemdiff

Key Concepts:

The Roadmap to v1.0.0

I Need Your Feedback!

How I Built Inline Disable Comments for a Go Markdown Linter

The Problem

What We Need to Support

The Data Model

lineDisable

disabledSet

blockState

Parsing: Step 1 — Extracting a Directive from a Line

Parsing: Step 2 — Building the disabledSet

Priority: What Wins When Rules Conflict?

Integration: Filtering Violations

Intentional "Silent Fail" for Invalid Rule Names

Testing Strategy

The Full Picture

How to add a markdown quality gate to your GitHub Actions workflow

Step 1: Create the workflow file

Step 2: Add the job skeleton

Step 3: Add the markdown linter to your GitHub Actions job

Step 4: See a real failure

Step 5: Add a config file

Step 6: Make the markdown lint check block merges

What the rules actually catch

What it doesn't solve yet

Footnote: why gomarklint over markdownlint-cli2

Shipping a Go CLI to Every Ecosystem: GitHub Releases, Homebrew, and npm

The Problem: Great Tools Die in Obscurity

Why Multi-Channel Distribution Matters

The Architecture: One Binary, Thin Wrappers

Step 1: Platform Detection (install.js)

Step 2: The CLI Wrapper (cli.js)

Step 3: Supply Chain Security

SHA-256 Checksum Verification

npm Provenance

Step 4: Automated Publishing with GoReleaser

Step 5: GoReleaser Configuration

Gotcha: The Checksums Filename

The Result

Takeaways

Choosing a Markdown linter for your docs pipeline: what each tool actually covers

The tools and what they actually do

If you need the broadest rule coverage: markdownlint

If you need AST-level extensibility: remark-lint

If you need format + dead-link validation in one binary, no runtime: gomarklint

How the rules map across tools

Quick-reference decision guide

Try gomarklint

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

The Problem with Current Solutions (Including AI)

The Solution: gosemdiff

Key Concepts:

The Roadmap to v1.0.0

I Need Your Feedback!

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

The Cache: Preventing 'Barrages'

The Semaphore: Respecting Resource Limits

The Retry: Tolerating Network 'Whims'

The "Negative Caching" Trap

Conclusion: Is it 100% Stable?

Catch broken links in your Markdown docs before they reach production

The Three Kinds of Broken Links

The CI Hook: Failing the Build Before the PR Merges

The "Redirect Mask" Trap

What's Not Solved Yet

Building a Culture of Documentation Quality in CI/CD

Introduction: Documentation as a Cultural Signal

`lineDisable`

`disabledSet`

`blockState`

Parsing: Step 2 — Building the `disabledSet`