gomdlint
gomdlint is a fast, self-fixing Markdown linter written in Go by yaklabco, with 55 markdownlint-compatible rules for CommonMark and GitHub Flavored Markdown. It honours markdownlint inline comments and can convert an existing markdownlint config.
Set up
Install and help10
- Install with Homebrew on macOS or Linux
- Install the latest release with Go
- Print version, commit hash and build date
- List commands and global flags
- Show every lint flag with its default
- Load fish completions in the current shell
- Install fish completions for new shells
- Print the zsh completion script
- Print the bash completion script
- Print the PowerShell completion script
Everyday
Linting11
- Lint every .md and .markdown file under the current directory
- Lint one directory recursively
- Lint a single file
- Lint several paths in one run
- Parse as GitHub Flavored Markdown, which turns on table rules
- Parse as plain CommonMark, the default
- Skip files matching a glob, repeatable
- Set the number of parallel workers, 0 means auto
- Fail the run on warnings as well as errors
- Use a specific config file
- Enable debug logging
Output formats12
- Human-readable report with source context, the default
- Columnar table of file, location, message and rule
- One table per file
- Counts per rule and per file
- Show the files table before the rules table
- Machine-readable JSON with rule IDs, names and fixes
- SARIF 2.1.0 for GitHub code scanning
- Name rules by ID, such as MD009
- Name rules as MD009/no-trailing-spaces
- Name rules as no-trailing-spaces, the default
- Hide the source line and caret under each issue
- Plain output, also accepts auto or always
Fixing8
- Apply automatic fixes in place
- Report what would be fixed without writing files
- Preview the fixes as a unified diff
- Only apply fixes from the listed rule IDs
- Fix without writing backup files
- Sidecar backup written next to each fixed file by default
- Keep reporting a rule but never auto-fix it
- Shows fixable=yes for the 37 rules that can auto-fix
Rule selection10
- List all rules with severity, fixability and description
- List rules as ID/name pairs
- Turn off a rule for this run, by rule ID
- Turn off several rules at once
- Turn on an opt-in rule for this run, by rule ID
- Disable a rule in the config file
- Config keys accept rule IDs or names
- Rule severity, one of error, warning or info
- Legacy aliases for MD025 and MD041
- Legacy aliases for MD004, MD012 and MD022
Workflows
CI and exit codes7
- Fail the build on warnings as well as errors
- Write SARIF for GitHub code scanning
- Upload results.sarif in a GitHub Actions step
- Save a machine-readable report
- Compact plain output for CI logs
- No errors, warnings alone pass unless --strict is set
- Errors found, warnings under --strict, or the command failed
Configure
Inline comments11
- Disable all rules until a matching enable
- Re-enable all rules
- Disable one or more space-separated rules
- Re-enable specific rules
- Suppress rules on the line holding the comment
- Suppress rules on the following line
- Disable rules for the whole file
- Enable rules for the whole file
- Save the current enabled rule state
- Return to the last captured state
- An ID like MD013, a name like line-length, or a rule tag
Config files and migration12
- Write a minimal .gomdlint.yml in the current directory
- Write a template listing every rule
- Write .gomdlint.json, load it with --config
- Write to a custom path, overwriting any existing file
- Project config, searched upward to the repo root, .gomdlint.yaml also works
- User config under $XDG_CONFIG_HOME
- System-wide config
- Find a markdownlint config here and convert it to .gomdlint.yml
- Convert a specific markdownlint file
- Write the converted config to a custom path
- markdownlint formats migrate can convert
- JavaScript configs need manual migration
Config keys10
- Markdown flavor, commonmark or gfm
- Glob patterns of files to skip
- Per-rule settings keyed by rule ID or name
- Turn a rule off, or true to turn an opt-in rule on
- Override severity with error, warning or info
- Stop a rule from fixing while it still reports
- Pass rule-specific options
- Baseline rule settings applied before rules, written by migrate
- Comma-separated ignore globs from the environment
- Disable fix backups from the environment
Rule options13
- Maximum line length, default 120
- Separate limits for headings and code blocks
- Skip table lines, code blocks and URLs are skipped by default
- Heading style, atx, atx_closed, setext or consistent
- Bullet style, dash, plus, asterisk or consistent
- Spaces per nested unordered list level
- Ordered list numbering, one, zero or ordered
- Only flag duplicate headings that share a parent
- Turn on the HTML rule and allow some elements
- Restrict fenced code languages to a list
- Enforce capitalisation of proper names
- Code block style, fenced, indented or consistent
- Fence character, backtick, tilde or consistent
Reference
Heading rules13
- Heading levels go up one at a time
- Consistent ATX or setext headings, fixable
- Space after the hash in ATX headings, fixable
- Only one space after the hash, fixable
- Spaces inside closed ATX hashes, fixable
- Single spaces inside closed ATX hashes, fixable
- Blank lines around headings, fixable
- Headings start at the beginning of the line, fixable
- No repeated heading text
- Only one top-level heading per document
- No trailing punctuation in headings, fixable
- First line is a top-level heading, opt-in
- Enforce a required heading structure, opt-in
List and blockquote rules8
- Consistent bullet markers, fixable
- Same indentation for items at one level, fixable
- Unordered list nesting indentation, fixable
- Ordered list number prefixes, fixable
- Spaces after list markers, fixable
- Blank lines around lists, fixable
- One space after the blockquote marker, fixable
- No blank lines inside a blockquote
Whitespace and code rules11
- No trailing whitespace, fixable
- No hard tab characters, fixable
- Collapse consecutive blank lines, fixable
- Lines stay under the configured maximum, fixable
- Files end with exactly one newline, fixable
- No dollar prompts on commands without output, fixable
- Blank lines around fenced code blocks, fixable
- No padding spaces inside code spans, fixable
- Fenced code blocks declare a language, fixable
- Consistent fenced or indented code blocks
- Consistent backtick or tilde fences, fixable
Link and image rules11
- Catch (text)[url] written backwards, fixable
- Wrap bare URLs in angle brackets, fixable
- No padding spaces inside link text, fixable
- Links need both text and destination
- Images need alt text
- Fragment links point at real headings
- Reference links use defined labels
- Remove unused reference definitions, fixable
- Consistent link and image style, opt-in
- Avoid vague link text like click here, opt-in
- Consistent link destination style, opt-in
Emphasis, HTML and table rules12
- Consistent horizontal rule style, fixable
- Use a real heading instead of bold text, fixable
- No spaces inside emphasis markers, fixable
- Consistent emphasis markers, fixable
- Consistent strong markers, fixable
- Flag inline HTML outside an allow list, opt-in
- Correct capitalisation of names, fixable, opt-in
- Consistent leading and trailing table pipes
- Every table row has the same column count
- Blank lines around tables, fixable, info severity
- Consistent table column style, opt-in
- Well-formed table delimiter row, fixable