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

Safe and Unsafe Fixes

Fixes come in two safety levels. A plain --fix applies only safe fixes, which tidy syntax without changing what the document means. Fixes that could change meaning—such as the empty-values fix, which deletes the empty key— are unsafe and skipped by default. When unsafe fixes are available but were not applied, the CLI reports how many; pass --unsafe-fixes to apply them too:

panache lint --fix --unsafe-fixes document.qmd

--unsafe-fixes only takes effect alongside --fix. See Fix safety for details, including how unsafe fixes behave in the editor.

CI Mode

panache lint exits with code 1 whenever any violations are found, so it works in a CI/CD pipeline without any extra flags:

panache lint .

Note

The --check flag is deprecated and now a no-op: exiting non-zero on violations is the default behavior. It is still accepted for backward compatibility but will be removed in a future release.

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

Human output highlights the reported issue and shows any suggested fix on a separate help line. The highlighted location matches short output, even when the fix edits a larger range of source text.

Lint Rules

Panache includes several built-in lint rules that analyze document structure and content. See the Lint Rules reference for the complete catalog, 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 = "arity"
julia = "fatou"
latex = "badness"
python = "ruff"
sh = "shellcheck"
js = "eslint"
go = "staticcheck"
rust = "clippy"

Available external linters:

Language	Linter	Description
R	`arity`	R linter with JSON diagnostics
R	`jarl`	R linter with JSON diagnostics
Julia	`fatou`	Julia linter with JSON diagnostics
LaTeX	`badness`	LaTeX 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 and executable inline expressions:

Collection: Code blocks and executable inline expressions of the target language are extracted in document order, with any enclosing container syntax (block quote markers, list item indentation) stripped so the linter sees valid code
Concatenation: Code that shares an execution context is joined, retaining blank-line padding where possible
Analysis: The external linter analyzes the combined code, treating inline expression results as used values
Mapping: Diagnostics are mapped back to original document positions, accounting for each line’s stripped container prefix

Note

This approach correctly handles stateful code. If a variable is defined in one executable code block and used in another executable block or an inline expression, the linter sees both the definition and the use.

Under the Quarto flavor, inline analysis supports `r expression`, `{r} expression`, `{python} expression`, and `{julia} expression`. R Markdown supports the classic R form. These follow the rmarkdown-inline-code and quarto-inline-code extension settings. Ordinary code spans and escaped examples using extra backticks or doubled braces are excluded.

Under the Quarto flavor, executable chunks and inline expressions share a lint context for each language. Displayed fences such as ```r and ```{.r}, and chunks with a literal eval: false (or eval=FALSE), are each linted independently. Their assignments cannot satisfy references in executable code or conflict with its definitions. They still receive diagnostics and fixes. Hashpipe options override options in the fence header. Expression-valued options such as eval: !expr false leave the chunk in the executable context. Options such as echo: false and include: false hide output but leave the chunk in the executable context. Panache uses explicit cell options for this grouping; it does not evaluate option expressions or infer runtime changes to defaults.

Under the Quarto flavor, external linters also analyze code from include shortcodes in inclusion order. Nested include paths resolve relative to the main document; paths starting with / resolve from the project root. Repeated includes contribute code at each occurrence. An include that is missing, unreadable, or cyclic prevents external analysis of that execution context and produces an include diagnostic instead.

Panache uses known parent documents when linting a partial directly. It discovers parents among the project’s render targets and the documents selected for the current lint command. Without a known parent, the partial is analyzed on its own. Diagnostics point to the file containing the code. A finding specific to a parent names that parent in a note; identical findings from several parents are combined.

lint --fix edits only the command’s target files, including files selected by a directory scan. Findings in other included files are reported but do not modify those files. A fix in shared source is available only when every known execution context and repeated occurrence agrees on its edits, even with --unsafe-fixes. Fixes spanning source files are omitted. With --stdin-filename, include resolution uses that filename and the supplied input replaces its on-disk contents for analysis; fixes still write only to stdout.

Note

For a code block nested in a block quote or list item, an autofix that would add or remove whole lines cannot be applied without disturbing the surrounding container syntax, so such fixes are dropped and only the diagnostic is reported. Fixes that stay within a single line apply normally.

Inline fixes must stay within expression content. Fixes that cross expression boundaries, introduce backticks or line breaks, remove existing line breaks, or leave an empty expression are omitted while retaining the diagnostic.

Example

Document with multiple R code blocks:

---
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 arity, fatou, badness, jarl, ruff, and eslint). Fixes that the linter marks as unsafe (arity, fatou, badness, ruff) are only applied under --unsafe-fixes. Requires badness 0.14+ for LaTeX (earlier versions lack JSON output and are skipped).

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
blank-line-in-display-math = true
blank-line-in-inline-footnote = true
duplicate-reference-labels = true
undefined-references = true
unused-definitions = true
duplicate-yaml-anchor = true
unused-yaml-anchor = true
citation-keys = true
citation-nonbreaking-space = true
unspaced-citation = true
unspaced-list-marker = true
chunk-label-spaces = true
missing-chunk-labels = true
figure-crossref-captions = true
unknown-emoji-alias = true
inline-math-line-break = true

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

[lint.rules]
undefined-references = false

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.