Intro

Markdown inting often gets overlooked in CI pipelines — until an inconsistent heading or a broken link slips into production. With gomarklint, you can catch these issues early, without slowing down your workflow. In this guide, we’ll walk through setting up gomarklint in GitHub Actions, customizing its configuration, and ensuring your Markdown stays clean and consistent across your repository. By the end, you’ll have a fully automated linting process that runs in milliseconds.

Why Lint Markdown in CI?

Markdown may seem “simple,” but small formatting errors can cause big issues in documentation or blog posts. Heading jumps confuse readers, broken links frustrate them, and inconsistent formatting hurts brand consistency. Linting in CI catches these issues early — before they reach production.

Installing gomarklint Locally

You can install gomarklint using `go install` or download pre-built binaries from the GitHub Releases page. Once installed, running `gomarklint init` generates a .`gomarklint.json` config file in your repository. This file defines default rules and file patterns, which can be overridden via CLI flags.

Setting Up GitHub Actions

Integrating gomarklint with GitHub Actions is straightforward. A minimal `.github/workflows/lint.yml` file checks out your code and runs the official gomarklint-action. If `.gomarklint.json` is missing, the action fails immediately, ensuring consistent configurations across environments.

Customizing for Your Project

You can enable external link checking for stricter validation, skip certain URLs with regex patterns, or adjust the minimum heading level to fit your style guide. For large repos, consider running link checks only in nightly builds to save time during PR reviews.

Full Example Workflow

In practice, a PR with broken links or heading issues will fail the CI run, prompting contributors to fix problems before merging. This reduces manual review time and ensures your docs stay clean and consistent.

Wrapping Up

Adding gomarklint to your CI pipeline is a small change that delivers a big payoff. It keeps your Markdown clean, consistent, and free of broken links — all without slowing down your builds. Once it’s in place, you’ll wonder how you managed without it.

Try It Out on Your Repository

You can get started in just a few minutes:

Repository:

GitHub Action:

https://github.com/marketplace/actions/gomarklint-markdown-linter

Install it locally, run gomarklint init to create your config, and commit it to your repo. From there, add the GitHub Action and let your CI handle the rest — catching issues automatically before they make it to production.