Linting

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.

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.

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:

panache lint document.qmd

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

panache lint file1.md file2.qmd file3.Rmd

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

panache lint .
panache lint docs/

panache lint supports glob patterns as well:

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

Lint from stdin

You can also pipe content through the linter:

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

Or with a here-document:

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

Apply Automatic Fixes

Panache can automatically fix certain types of issues:

panache lint --fix document.qmd

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:

panache lint --check .

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

panache lint --check . || exit 1

Message format

Use --message-format to control diagnostic verbosity:

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

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

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

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:

---
title: "Analysis"
---


::: {.cell}

```{.r .cell-code}
x <- 10
```
:::


Some text between blocks.


::: {.cell}

```{.r .cell-code}
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:

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:

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

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 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).

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

[lint.rules]
undefined-references = false

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 for editor configuration details.

Examples

Example 1: Heading Hierarchy

Before:

# Main Title

### Skipped Level

#### Another Skip

Run linter:

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:

panache lint --fix document.qmd

After:

# Main Title

## Skipped Level

### Another Skip

Example 2: Duplicate References

Before:

See [example1] and [example2].

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

Run linter:

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

See [example1] and [example2].

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

Example 3: Citation Validation

Before (with refs.bib configured):

---
bibliography: refs.bib
---

See @existingkey and @missingkey.

Run linter:

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.