Markdown Linting

Markdown Linting

Quarto documents should follow standard markdownlint rules. This file covers only Quarto-specific allowances and configuration — refer to the markdownlint docs for general rules.

Quarto-Specific Allowances

Line Length (MD013)

Typically disabled for Quarto — prose paragraphs may be long and YAML/code lines can exceed limits.

Duplicate Headings (MD024)

Repeated headers are common in structured Quarto documents (e.g., repeated "Example" sections).

Multiple H1 (MD025)

Quarto documents may have multiple H1 headers, especially in books and multi-part documents.

Inline HTML (MD033)

Quarto uses HTML in specific contexts:

• Shortcodes: {{< shortcode >}}
• Raw HTML blocks: ```{=html}
• Elements like <div>, <span>, <iframe> for advanced layouts

First Line H1 (MD041)

Quarto uses YAML front matter before the first heading, so MD041 should be disabled.

Configuration

Example .markdownlint.yaml

default: true

MD013: false
MD024: false
MD025: false
MD033:
  allowed_elements:
    - div
    - span
    - iframe
MD041: false

Example .markdownlint-cli2.yaml

config:
  default: true
  MD013: false
  MD024: false
  MD025: false
  MD041: false

globs:
  - "**/*.md"
  - "**/*.qmd"

Quarto Div Formatting

When using fenced divs, ensure proper blank-line spacing:

Some text.

::: {.callout-note}
Note content here.
:::

More text.

Key points:

• Blank line before opening :::.
• Blank line after closing :::.
• Use :::: (four+ colons) for nesting outer divs.

Resources

• markdownlint Rules
• markdownlint-cli2
• Quarto Markdown Basics