---
title: Linting
description: >
  This section provides instructions and examples for using the Panache linter,
  which checks for correctness issues and best practice violations in your
  Markdown documents.
---

Panache includes a built-in linter that checks for correctness issues and best
practice violations in your Markdown documents. Unlike the formatter which
handles style consistency, the linter catches semantic problems like syntax
errors, heading hierarchy issues, broken references, and citation problems.

::: {.callout-tip}
For the full catalogue of built-in lint rules, the diagnostic codes each rule
emits, severity, and auto-fix support, see the [Lint Rules
reference](../reference/linter-rules.qmd).
:::

## Philosophy

The linter focuses on semantic correctness rather than stylistic preferences,
for which the formatter is responsible (and can act as a linter via
`panache format --check`).

## CLI Usage

### Basic Linting

To lint a single file and show diagnostics, run this:

```bash
panache lint document.qmd
```

To lint multiple files at once, you can specify them one-by-one:

```bash
panache lint file1.md file2.qmd file3.Rmd
```

If you want to lint all supported files in a directory, use:

```bash
panache lint .
panache lint docs/
```

`panache lint` supports glob patterns as well:

```bash
panache lint 'src/**/*.qmd'
```

### Lint from stdin

You can also pipe content through the linter:

```bash
cat document.qmd | panache lint # or `panache lint < document.qmd`
```

Or with a here-document:

```bash
panache lint <<'EOF'
# H1
### H3
EOF
```

### Apply Automatic Fixes

Panache can automatically fix certain types of issues:

```bash
panache lint --fix document.qmd
```

::: {.callout-warning}
Auto-fix modifies files in place. Always commit your changes first or use
version control.
:::

### CI Mode

If you want to enforce linting in a CI/CD pipeline, use the `--check` flag. This
will run the linter and exit with code 1 if any violations are found:

```bash
panache lint --check .
```

This mode is ideal for enforcing linting in CI/CD pipelines:

```bash
panache lint --check . || exit 1
```

### Message format

Use `--message-format` to control diagnostic verbosity:

```bash
panache lint --message-format human document.qmd # default rich output
panache lint --message-format short document.qmd # GNU-style one-line diagnostics
```

## Lint Rules

Panache includes several built-in lint rules that analyze document structure and
content. See the [Lint Rules reference](../reference/linter-rules.qmd) for the
complete catalogue, including each rule's diagnostic codes, severity, auto-fix
status, and configuration requirements.

## External Linters

Panache can integrate with external code linters to check code blocks within
your documents.

### Configuration

Enable external linters in your configuration file:

```toml
[linters]
r = "jarl"
python = "ruff"
sh = "shellcheck"
js = "eslint"
go = "staticcheck"
rust = "clippy"
```

Available external linters:

  | Language              | Linter        | Description                         |
  | --------------------- | ------------- | ----------------------------------- |
  | R                     | `jarl`        | R linter with JSON diagnostics      |
  | Python                | `ruff`        | Python linter with JSON diagnostics |
  | Shell                 | `shellcheck`  | Shell linter with JSON diagnostics  |
  | JavaScript/TypeScript | `eslint`      | JS/TS linter with JSON diagnostics  |
  | Go                    | `staticcheck` | Go linter with JSON diagnostics     |
  | Rust                  | `clippy`      | Rust linter with JSON diagnostics   |

### How External Linters Work

External linters analyze code blocks using a stateful concatenation approach:

1. **Collection**: All code blocks of the target language are extracted
2. **Concatenation**: Blocks are joined with blank-line preservation to maintain
   line numbers
3. **Analysis**: The external linter analyzes the concatenated code
4. **Mapping**: Diagnostics are mapped back to original document positions

::: {.callout-note}
This approach correctly handles stateful code. If a variable is defined in one
code block and used in another, the linter sees the complete context and won't
report false positives.
:::

### Example

Document with multiple R code blocks:

````markdown
---
title: "Analysis"
---

```{r}
x <- 10
```

Some text between blocks.

```{r}
y <- x + 5
```
````

With `[linters] r = "jarl"` configured, `jarl` analyzes both blocks together and
correctly understands that `x` is defined before it's used. Similarly, with
`[linters] python = "ruff"`, Ruff can lint Python code blocks and map
diagnostics back to the original document.

### Behavior

Language matching
:   Case-insensitive matching of code block language to linter configuration

Error handling
:   Missing linter executables log a warning and skip gracefully

Compatibility checks
:   External linters only run for their supported languages. Unsupported
    mappings in `[linters]` (for example, `bash = "jarl"`) are skipped with a
    warning.

Timeout
:   30-second timeout per linter invocation

Line accuracy
:   Diagnostics report exact line and column positions in the original document

Auto-fixes
:   Supported for external linters that return fix edits with mappable ranges
    (currently `jarl`, `ruff`, and `eslint`)

### Where External Linters Run

CLI
:   Diagnostics appear in `panache lint` output

LSP
:   Diagnostics appear inline in your editor with live updates

## Ignore Directives

You can selectively disable linting for specific regions using HTML comment
directives:

### Ignore Linting Only

Use `panache-ignore-lint-start` and `panache-ignore-lint-end` to suppress lint
warnings:

```markdown
Normal content will be linted.

<!-- panache-ignore-lint-start -->
#### This heading skip won't trigger heading-hierarchy warning
<!-- panache-ignore-lint-end -->

Back to normal linting.
```

This is useful for:

- Intentional heading level skips for specific formatting
- Generated content with unusual structure
- Third-party content you don't control
- Documentation examples showing bad practices

#### Ignore Both Formatting and Linting

Use `panache-ignore-start` and `panache-ignore-end` to disable both:

```markdown
<!-- panache-ignore-start -->
#### Unusual   structure   here
Both formatting and linting ignored in this region
<!-- panache-ignore-end -->
```

::: {.callout-note}
**Note on Directive Behavior**: Lint rules still "see" content in ignored
regions when tracking context (e.g., for heading hierarchy), but diagnostics
from ignored regions are filtered out. This ensures rules maintain proper state
across the document.
:::

See [Formatting](formatting.qmd) for more information about formatting-specific
ignore directives.

## Configuration

Lint rules can be configured in the `[lint.rules]` section of your configuration
file. Each key is a rule name and each value is a boolean (`true`/`false`).

```toml
[lint.rules]
heading-hierarchy = true
duplicate-reference-labels = true
undefined-references = true
unused-definitions = true
citation-keys = true
chunk-label-spaces = true
missing-chunk-labels = true
figure-crossref-captions = true
unknown-emoji-alias = true
```

All rules are enabled by default when omitted. You can disable a specific rule:

```toml
[lint.rules]
undefined-references = false
```

::: {.callout-note}
Legacy `[lint] rule = true/false` is still supported for backward compatibility,
but deprecated.
:::

## LSP Integration

When using the Panache language server, lint diagnostics appear live in your
editor as you type:

- Squiggly underlines for errors and warnings
- Hover tooltips showing diagnostic messages
- Code actions for auto-fixes (e.g., fix heading hierarchy)

See the [LSP documentation](lsp.qmd) for editor configuration details.

## Examples

### Example 1: Heading Hierarchy

Before:

```markdown
# Main Title

### Skipped Level

#### Another Skip
```

Run linter:

```bash
panache lint document.qmd
```

Output:

```
warning: [heading-hierarchy] Heading level skipped from h1 to h3; expected h2
 --> document.qmd:3:1
  |
3 | ### Skipped Level
  | ^^^^^^^^^^^^^^^^^^

warning: [heading-hierarchy] Heading level skipped from h3 to h4; expected h3
 --> document.qmd:5:1
  |
5 | #### Another Skip
  | ^^^^^^^^^^^^^^^^^
```

Apply auto-fix:

```bash
panache lint --fix document.qmd
```

After:

```markdown
# Main Title

## Skipped Level

### Another Skip
```

### Example 2: Duplicate References

Before:

```markdown
See [example1] and [example2].

[example1]: https://first.com
[example1]: https://second.com
[example2]: https://other.com
```

Run linter:

```bash
panache lint document.qmd
```

Output:

```
warning[duplicate-reference-labels]: Duplicate reference definition 'example1'
  --> document.qmd:4:1
note: First defined here:
  --> document.qmd:3:1
```

Resolution (manual):

```markdown
See [example1] and [example2].

[example1]: https://first.com
[example2]: https://other.com
```

### Example 3: Citation Validation

Before (with `refs.bib` configured):

```markdown
---
bibliography: refs.bib
---

See @existingkey and @missingkey.
```

Run linter:

```bash
panache lint document.qmd
```

Output:

```
warning[citation-keys]: Citation key 'missingkey' not found in bibliography
  --> document.qmd:5:24
```

Resolution: Add the citation to `refs.bib` or remove the reference.
