MkDocs Material Linter

A VS Code extension tailored for MkDocs Material

Features:

Flags common syntax mistakes in the Problems panel
Adds clearer visual cues for blocks, tables, and inline features
Ships with built‑in light/dark themes for best results

1. Who It’s For

If you write MkDocs Material docs (admonitions, content tabs, tables, task lists, etc.), this helps you catch issues early and keep docs readable.

2. Best Practices

Heading styles
Admonition highlight
Nested admonition bars
Tables (border + header)
Tabs syntax
Diagnostics in Problems panel
Math blocks
Blockquotes
Code blocks
Front matter (---)
Images
Icons & emojis
Footnotes & tooltips

3. Themes

Two built-in themes are provided for best highlighting:

MkDocs Material Linter (Light)
MkDocs Material Linter (Dark)

VS Code → Preferences → Color Theme → select one of the above.
You can also use diagnostics without switching themes.

4. Theory about What It Does

We highly recommend using the provided themes to get the full benefit of the extension, but diagnostics will work regardless of theme.

4.1 Diagnostics (Errors/Warnings)

Area	Rule	Example
Admonition	marker must have a type	`!!! note`, `???+ question`
Admonition	type must be a simple identifier	letters/numbers/`_`/`-`
Admonition	unknown type → warning	`!!! foo`
Admonition	title quotes must close	`!!! note "Title"`
Admonition	content must be indented	4 spaces or 1 tab
Admonition	blank line before non‑list content	list can follow immediately
Tabs	must be `=== "Title"` or `=== 'Title'`	quotes required
Tabs	content must be indented	4 spaces or 1 tab
Lists	marker must be followed by a space	`- item`, `1. item`
Lists	blank line before a list in normal text	avoids `-item` look
Tables	header must be followed by separator	`\| --- \|`
Tables	separator column count must match header	consistent columns
Code blocks	fence must be closed	``` / ~~~
Math	`$$` blocks must be closed	`$$ ... $$`

4.2 Visual Cues

Admonitions: narrow color bars + subtle background (nested blocks show multiple bars)
Tables: soft background + stronger header + outer border + row separators
Headings, blockquotes, icons/emojis, math, footnotes, etc. are more distinct
Code blocks: dark background with light text for readability

5. Supported Files

Markdown (.md)
MDX (.mdx)

6. Configuration

You can customize the linter behavior in VS Code settings:

Setting	Default	Description
`checkBlankLineBeforeList`	`true`	Require blank line before lists in normal text
`checkBlankLineBeforeAdmonitionContent`	`false`	Require blank line before admonition content (except lists)
`checkIndentation`	`true`	Check indentation for admonitions and tabs

Example (settings.json):

{
  "mkdocs-material-linter.checkBlankLineBeforeList": true,
  "mkdocs-material-linter.checkBlankLineBeforeAdmonitionContent": false,
  "mkdocs-material-linter.checkIndentation": true
}

7. Additional Shortcuts

VS Code doesn't have built-in shortcuts for some of the rich text format shortcuts MkDocs Material supports. Here are some useful ones:

Underline (MkDocs ^^underline^^): Ctrl+U / Cmd+U

8. Quick Diagnose

8.1 Correct

!!! note "Title"
    This is valid.

???+ question "FAQ"
    - First item
    - Second item

=== "Tab A"
    Tab content.

| Method | Description |
| --- | --- |
| GET | Fetch |

8.2 Common Mistakes

!!!note
Text not indented.

=== Tab A
    Missing quotes.

-item
1.item

Mkdocs Material Linter

ytianle