gomarklint

https://shinagawa-web.github.io/gomarklint/
Admin
gomarklint is a fast Markdown linter built in Go that validates internal anchors and external URLs,...
Tokens:16,163
Snippets:143
Trust Score:9.7
Update:1 month ago
Show doc for...
Tokens:
Raw
### Configuration File Example

Source: https://shinagawa-web.github.io/gomarklint/docs/cli

An example of a .gomarklint.json configuration file defining rule severities.

```json
{
  "rules": {
    "no-setext-headings": "warning",
    "unclosed-code-block": "error"
  }
}
```

--------------------------------

### Install gomarklint via go install

Source: https://shinagawa-web.github.io/gomarklint/docs/quick-start

Install gomarklint using Go's install command. Requires Go.

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

--------------------------------

### CLI Execution Examples

Source: https://shinagawa-web.github.io/gomarklint/docs/cli

Examples of running the tool with different files and severity flags, showing the resulting output and exit status.

```bash
$ gomarklint README.md
  README.md:10: [warning] no-setext-headings: Setext heading found
  README.md:20: [error]   unclosed-code-block: Unclosed code block

⚠ 1 warning, ✖ 1 error — exit 1

$ gomarklint README.md --severity error
  README.md:20: [error] unclosed-code-block: Unclosed code block

✖ 1 issues found — exit 1

$ gomarklint docs/  # only warnings, no errors → exit 0
  docs/style.md:5: [warning] no-setext-headings: Setext heading found

⚠ 1 warning found — exit 0
```

--------------------------------

### Install gomarklint binary on Windows

Source: https://shinagawa-web.github.io/gomarklint/docs/quick-start

Download and extract the binary for Windows, then add it to the user PATH. Run the PATH command once.

```powershell
# 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")
```

--------------------------------

### Install gomarklint

Source: https://shinagawa-web.github.io/gomarklint/docs/migration

Commands to install the gomarklint binary via various package managers or shell scripts.

```bash
# macOS / Linux
curl -fsSL https://raw.githubusercontent.com/shinagawa-web/gomarklint/main/install.sh | sh

# Homebrew
brew install shinagawa-web/tap/gomarklint

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

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

--------------------------------

### Example gomarklint configuration

Source: https://shinagawa-web.github.io/gomarklint/docs/configuration

A complete example configuration showing top-level fields and rule customization. The default field enables opt-out mode, include defaults to ["README.md", "testdata"], and output can be text or json.

```json
{
  "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"
}
```

--------------------------------

### Install gomarklint via npm

Source: https://shinagawa-web.github.io/gomarklint/docs/quick-start

Install gomarklint globally via npm. Requires Node.js and npm.

```bash
npm install -g @shinagawa-web/gomarklint
```

--------------------------------

### Install gomarklint via curl, Homebrew, or npm

Source: https://shinagawa-web.github.io/gomarklint

Install gomarklint on macOS/Linux via the one-line install script, Homebrew, or npm. Choose the method that fits your environment; all three install the same CLI.

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

```bash
brew install shinagawa-web/tap/gomarklint
```

```bash
npm install -g @shinagawa-web/gomarklint
```

--------------------------------

### GitHub Actions workflow with remark-cli before migration

Source: https://shinagawa-web.github.io/gomarklint/docs/migration

Example of a GitHub Actions workflow using remark-cli to lint Markdown. This is the 'Before' CI setup to be replaced with gomarklint-action.

```yaml
- name: Install remark
  run: npm install -g remark-cli remark-preset-lint-recommended

- name: Lint Markdown
  run: remark --use remark-preset-lint-recommended .
```

--------------------------------

### Install gomarklint binary on macOS/Linux

Source: https://shinagawa-web.github.io/gomarklint/docs/quick-start

Download and extract the binary for macOS or Linux, then move it to a directory in PATH. The user-local option avoids sudo.

```bash
# 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/
```

--------------------------------

### Quick Start GitHub Actions workflow for gomarklint

Source: https://shinagawa-web.github.io/gomarklint/docs/github-actions

Quick Start workflow for running gomarklint on pull requests that modify Markdown files. It checks out the repository, sets up Go 1.23, and runs the official gomarklint GitHub Action.

```yaml
# .github/workflows/docs-lint.yml
name: gomarklint

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

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

      - uses: actions/setup-go@v5
        with:
          go-version: '1.23'

      - uses: shinagawa-web/gomarklint-action@v1
```

--------------------------------

### remark-lint configuration before migration (.remarkrc.mjs)

Source: https://shinagawa-web.github.io/gomarklint/docs/migration

Example of a remark-lint configuration file using remark-preset-lint-recommended and custom rules. This is the 'Before' configuration to be converted to gomarklint.

```javascript
import remarkPresetLintRecommended from 'remark-preset-lint-recommended'
import remarkLintMaximumLineLength from 'remark-lint-maximum-line-length'
import remarkLintEmphasisMarker from 'remark-lint-emphasis-marker'

export default {
  plugins: [
    remarkPresetLintRecommended,
    [remarkLintMaximumLineLength, 120],
    [remarkLintEmphasisMarker, '*'],
  ],
}
```

--------------------------------

### Opt-in configuration running only final-blank-line

Source: https://shinagawa-web.github.io/gomarklint/docs/configuration

With default set to false, only rules explicitly listed in rules will run. This example enables only final-blank-line.

```json
{ "default": false, "rules": { "final-blank-line": true } }
```

--------------------------------

### gomarklint configuration after migration (.gomarklint.json)

Source: https://shinagawa-web.github.io/gomarklint/docs/migration

Equivalent gomarklint configuration to the remark-lint example. Uses default rules and custom settings for max-line-length and consistent-emphasis-style.

```json
{
  "default": true,
  "rules": {
    "max-line-length": { "enabled": true, "lineLength": 120 },
    "consistent-emphasis-style": { "style": "asterisk" }
  }
}
```

--------------------------------

### Validate configuration

Source: https://shinagawa-web.github.io/gomarklint/docs/migration-v2

Run the linter with the specified configuration file to verify the setup. If the configuration format is incorrect, an error message will be displayed.

```bash
gomarklint --config .gomarklint.json README.md
```

```text
[gomarklint error]: failed to parse config file: ...
```

--------------------------------

### Default .gomarklint.json config

Source: https://shinagawa-web.github.io/gomarklint/docs/quick-start

Example .gomarklint.json created by `gomarklint init`. Shows default rule settings and config structure. CLI flags override these values.

```json
{
  "default": true,
  "rules": {
    "final-blank-line": true,
    "unclosed-code-block": true,
    "empty-alt-text": true,
    "fenced-code-language": true,
    "heading-level": { "severity": "error", "minLevel": 2 },
    "duplicate-heading": true,
    "no-multiple-blank-lines": true,
    "no-setext-headings": true,
    "single-h1": true,
    "blanks-around-headings": true,
    "no-bare-urls": true,
    "no-empty-links": true,
    "no-emphasis-as-heading": true,
    "blanks-around-lists": true,
    "blanks-around-fences": true,
    "no-hard-tabs": true,
    "no-trailing-punctuation": { "punctuation": ".,;:!" },
    "consistent-code-fence": { "style": "consistent" },
    "consistent-emphasis-style": { "style": "consistent" },
    "consistent-list-marker": { "style": "consistent" },
    "max-line-length": { "enabled": false, "lineLength": 80 },
    "external-link": { "enabled": false, "severity": "error", "timeoutSeconds": 5, "maxConcurrency": 10, "maxRetries": 2, "perHostConcurrency": 0, "perHostIntervalMs": 0, "skipPatterns": [] },
    "link-fragments": { "enabled": true, "slug-algorithm": "github" }
  },
  "include": ["README.md", "testdata"],
  "ignore": [],
  "output": "text"
}
```

--------------------------------

### Opt-out configuration disabling one rule

Source: https://shinagawa-web.github.io/gomarklint/docs/configuration

With default set to true, all unlisted rules are enabled. This example disables only no-setext-headings while keeping everything else enabled.

```json
{ "default": true, "rules": { "no-setext-headings": false } }
```

--------------------------------

### Initialize gomarklint config

Source: https://shinagawa-web.github.io/gomarklint/docs/quick-start

Initialize a .gomarklint.json config file with sensible defaults. Optional but recommended.

```bash
gomarklint init
```

--------------------------------

### Build gomarklint from source

Source: https://shinagawa-web.github.io/gomarklint/docs/quick-start

Build gomarklint from source. Requires Git and Go; make is optional.

```bash
git clone https://github.com/shinagawa-web/gomarklint
cd gomarklint
make build   # or: go build -o gomarklint .
```

--------------------------------

### Basic CLI Usage Syntax

Source: https://shinagawa-web.github.io/gomarklint/docs/cli

The standard command structure for running gomarklint on files or directories.

```bash
gomarklint [files or directories] [flags]
```

--------------------------------

### Single-line disable directives

Source: https://shinagawa-web.github.io/gomarklint/docs/disable-comments

Suppresses violations on the same line the directive appears. The first example disables all rules; the second disables only the named rule.

```markdown
https://example.com <!-- gomarklint-disable-line -->

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

--------------------------------

### GitHub Actions workflow with gomarklint-action after migration

Source: https://shinagawa-web.github.io/gomarklint/docs/migration

Replacement CI workflow using gomarklint-action. Sets up Go and runs the action.

```yaml
- uses: actions/setup-go@v5
  with:
    go-version-file: 'go.mod'

- uses: shinagawa-web/gomarklint-action@v1
```

--------------------------------

### Next-line disable directives

Source: https://shinagawa-web.github.io/gomarklint/docs/disable-comments

Suppresses violations on the line immediately following the directive. The first example disables all rules; the second disables only the named rule.

```markdown
<!-- gomarklint-disable-next-line -->
https://example.com

<!-- gomarklint-disable-next-line no-bare-urls -->
https://example.com
```

--------------------------------

### Run textlint and gomarklint in parallel via npm scripts

Source: https://shinagawa-web.github.io/gomarklint/docs/migration

Configure package.json scripts to execute both structural and prose linting sequentially.

```json
{
  "scripts": {
    "lint:structure": "gomarklint .",
    "lint:prose": "textlint **/*.md",
    "lint": "npm run lint:structure && npm run lint:prose"
  }
}
```

--------------------------------

### Regenerate the configuration file

Source: https://shinagawa-web.github.io/gomarklint/docs/migration-v2

The recommended approach to obtain a valid v2 configuration file is to remove the existing one and initialize a new one.

```bash
rm .gomarklint.json
gomarklint init
```

--------------------------------

### Convert markdownlint configuration

Source: https://shinagawa-web.github.io/gomarklint/docs/migration

Comparison of the configuration format between markdownlint and gomarklint.

```json
{
  "default": true,
  "MD013": { "line_length": 120 },
  "MD024": false,
  "MD026": { "punctuation": ".,;:!?" }
}
```

```json
{
  "default": true,
  "rules": {
    "max-line-length": { "enabled": true, "lineLength": 120 },
    "duplicate-heading": false,
    "no-trailing-punctuation": { "punctuation": ".,;:!?" }
  }
}
```

--------------------------------

### Run gomarklint with JSON output

Source: https://shinagawa-web.github.io/gomarklint/docs/quick-start

Run gomarklint with JSON output for CI or tooling. Exit code is non-zero if violations are found.

```bash
gomarklint . --output json
```

--------------------------------

### v1 Configuration Format

Source: https://shinagawa-web.github.io/gomarklint/docs/migration-v2

The legacy configuration format using flat boolean fields.

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

--------------------------------

### Enable opt-in mode

Source: https://shinagawa-web.github.io/gomarklint/docs/migration-v2

Setting 'default' to false disables all rules by default, requiring explicit activation of desired rules in the configuration.

```json
{
  "default": false,
  "rules": {
    "final-blank-line": true,
    "duplicate-heading": true
  }
}
```

--------------------------------

### Run gomarklint on files

Source: https://shinagawa-web.github.io/gomarklint/docs/quick-start

Run gomarklint on the current directory recursively or on specific targets. Exit code is non-zero if violations are found, zero otherwise.

```bash
# check current directory recursively
gomarklint .

# check specific targets
gomarklint docs README.md internal/rule
```

--------------------------------

### Configure per-directory workaround

Source: https://shinagawa-web.github.io/gomarklint/docs/migration

Exclude subdirectories from the root configuration and run the tool separately with a specific config file.

```json
{
  "ignore": ["docs/"]
}
```

```bash
gomarklint .                                   # root config
gomarklint docs/ --config docs/.gomarklint.json  # docs-specific config
```

--------------------------------

### Go Module Import Path Update

Source: https://shinagawa-web.github.io/gomarklint/docs/migration-v2

The updated import path for using gomarklint as a library.

```text
github.com/shinagawa-web/gomarklint   →   github.com/shinagawa-web/gomarklint/v2
```

--------------------------------

### v2 Configuration Format

Source: https://shinagawa-web.github.io/gomarklint/docs/migration-v2

The updated configuration format using a unified rules map.

```json
{
  "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"
}
```

--------------------------------

### Apply different rules to different directories

Source: https://shinagawa-web.github.io/gomarklint/docs/faq

To apply specific rules to a subdirectory, use the ignore field in the root configuration and run the command with an explicit config path for the subdirectory.

```json
{
  "ignore": ["docs/"]
}
```

```bash
gomarklint .                                     # root config for everything else
gomarklint docs/ --config docs/.gomarklint.json  # docs-specific config
```

--------------------------------

### Migrate markdownlint CI to gomarklint

Source: https://shinagawa-web.github.io/gomarklint/docs/migration

Updating GitHub Actions workflow from markdownlint-cli2 to the native gomarklint action.

```yaml
- uses: DavidAnson/markdownlint-cli2-action@v18
  with:
    globs: "**/*.md"
```

```yaml
- uses: actions/setup-go@v5
  with:
    go-version-file: 'go.mod'

- uses: shinagawa-web/gomarklint-action@v1
```

--------------------------------

### Enable rules incrementally

Source: https://shinagawa-web.github.io/gomarklint/docs/migration

Set default to false and explicitly enable only the desired rules to adopt the tool gradually.

```json
{
  "default": false,
  "rules": {
    "final-blank-line": true,
    "fenced-code-language": true
  }
}
```

--------------------------------

### Enable PR comment with gomarklint-action

Source: https://shinagawa-web.github.io/gomarklint/docs/github-actions

Configures the gomarklint action to post lint results as a comment on pull requests. The comment is automatically updated on subsequent runs, avoiding duplicates. Requires the job to have the `pull-requests: write` permission.

```yaml
- uses: shinagawa-web/gomarklint-action@v1
  with:
    comment-on-pr: 'true'
    github-token: ${{ secrets.GITHUB_TOKEN }}
```

--------------------------------

### Configure custom slug-algorithm

Source: https://shinagawa-web.github.io/gomarklint/docs/rules

Use the 'custom' slug algorithm by setting 'slug-algorithm' to 'custom' and providing specific 'slug-params' in the configuration.

```json
"link-fragments": {
  "enabled": true,
  "slug-algorithm": "custom",
  "slug-params": {
    "lowercase": true,
    "preserve-unicode": true,
    "space-replacement": "-",
    "strip-chars": "[^\\w\\- ]",
    "collapse-separators": true
  }
}
```

--------------------------------

### Verify link status with curl

Source: https://shinagawa-web.github.io/gomarklint/docs/faq

Use this curl command to check if a link is reachable using the same User-Agent as gomarklint.

```bash
curl -s -o /dev/null -w "%{http_code}\n" \
  -A "Go-http-client/1.1" \
  https://your-url-here
```

--------------------------------

### CLI Flags

Source: https://shinagawa-web.github.io/gomarklint/docs/migration-v2

The remaining CLI flags available in v2.

```bash
--config <path>     Path to config file (default: .gomarklint.json)
--output <format>   Output format: text or json
--severity <level>  Minimum severity to report: warning or error (new in v2)
```

--------------------------------

### Equivalent heading-level rule object forms

Source: https://shinagawa-web.github.io/gomarklint/docs/configuration

In the object form, enabled can be omitted and defaults to true. Both configurations are equivalent.

```json
"heading-level": { "enabled": true, "severity": "warning", "minLevel": 2 }
"heading-level": { "severity": "warning", "minLevel": 2 }
```

--------------------------------

### Configure severity levels

Source: https://shinagawa-web.github.io/gomarklint/docs/migration-v2

Rules can be set to 'warning' severity to prevent CI failure. Warnings are displayed but do not trigger a non-zero exit code.

```json
{
  "rules": {
    "no-setext-headings": "warning",
    "heading-level": { "enabled": true, "severity": "warning", "minLevel": 2 }
  }
}
```

--------------------------------

### Human-readable output format

Source: https://shinagawa-web.github.io/gomarklint/docs/output

The default output format displays errors per file and provides a summary of issues found along with execution statistics.

```text
❯ 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
```

--------------------------------

### Configure warning severity for migration

Source: https://shinagawa-web.github.io/gomarklint/docs/migration

Set the severity of specific rules to warning to allow running alongside other tools while fixing violations.

```json
{
  "default": true,
  "rules": {
    "no-bare-urls": { "severity": "warning" }
  }
}
```

--------------------------------

### Configure skipPatterns for academic or journal links

Source: https://shinagawa-web.github.io/gomarklint/docs/faq

Use the skipPatterns configuration to ignore domains that aggressively block automated HTTP clients, such as doi.org and wikipedia.org.

```json
{
  "skipPatterns": ["doi\\.org", "wikipedia\\.org"]
}
```

--------------------------------

### gomarklint invalid option validation error

Source: https://shinagawa-web.github.io/gomarklint/docs/configuration

Rule options are validated at startup. An invalid value such as "backticks" for consistent-code-fence.style causes gomarklint to exit with this descriptive error before linting runs, even when the rule is disabled.

```text
gomarklint: invalid value "backticks" for consistent-code-fence.style (valid values: consistent, backtick, tilde)
```

--------------------------------

### Uninstall legacy linters

Source: https://shinagawa-web.github.io/gomarklint/docs/migration

Commands to remove existing linter packages from your project.

```bash
# if you used markdownlint-cli2:
npm uninstall markdownlint-cli2

# if you used remark-lint:
npm uninstall remark remark-cli remark-lint remark-preset-lint-recommended

# if you used textlint:
npm uninstall textlint textlint-rule-*
```

--------------------------------

### Required permissions for PR comment

Source: https://shinagawa-web.github.io/gomarklint/docs/github-actions

Sets the minimum permissions needed for the gomarklint action to post PR comments. The `pull-requests: write` permission is required when using `comment-on-pr: 'true'`.

```yaml
permissions:
  contents: read
  pull-requests: write
```

--------------------------------

### Re-enable specific rule inside a block that disabled all

Source: https://shinagawa-web.github.io/gomarklint/docs/disable-comments

Shows how to re-enable a specific rule (no-bare-urls) inside a block that disabled all rules. The line after the specific enable is checked again for that rule.

```markdown
<!-- gomarklint-disable -->
https://example.com
<!-- gomarklint-enable no-bare-urls -->
https://example.com   ← no-bare-urls is checked again here
<!-- gomarklint-enable -->
```

--------------------------------

### Suppress false positive link-fragments with disable comments

Source: https://shinagawa-web.github.io/gomarklint/docs/faq

Use these comments to ignore specific link fragment errors when the slug algorithm produces an empty ID.

```markdown
<!-- gomarklint-disable link-fragments -->
[See section](#id1)
<!-- gomarklint-enable link-fragments -->
```
Tokens:
Raw