Markdown Code Assistant

Language-aware formatting and inline diagnostics for fenced code blocks in Markdown files.

Markdown Code Assistant treats the code examples inside your .md files as first-class citizens — routing them through the same formatters you use for standalone source files, and surfacing errors directly in the Markdown editor.

Features

• Format code blocks — sends each fenced block through Prettier, Black, or shfmt and writes the result back, leaving all surrounding Markdown untouched.
• Inline diagnostics — runs syntax and lint checks on code blocks and maps errors back to their exact lines in the Markdown file (Problems panel + gutter icons + inline text).
• Status bar item — a ✓ Markdown Code Assist indicator in the status bar shows when a Markdown file is active, transitions to ⚠ N issues when diagnostics find problems, and briefly shows ✓ Formatted N blocks after a format operation.
• Ignore directive — add @md-assistant-ignore to any fence's info string to exclude that block from formatting and diagnostics entirely (e.g. ```js @md-assistant-ignore).
• Zero-install shell support — shell (sh) formatting delegates to the mkhl.shfmt extension (auto-installed); ShellCheck diagnostics delegate to timonwong.shellcheck (auto-installed). No system tools required.
• Zero-install Python formatting — delegates to the ms-python.black-formatter extension (auto-installed). Python itself is not required for formatting.
• Deep Python diagnostics — Ruff runs fully in-process via @astral-sh/ruff-wasm-nodejs (bundled, no install required). Catches undefined names, unreachable code, style issues, and more. Falls back to pyflakes CLI, then py_compile if WASM fails.
• SQL formatting + diagnostics — prettier-plugin-sql is bundled; SQL blocks are formatted in-process and parse errors are surfaced as diagnostics. No external tools required.
• Format on Save — optional auto-format whenever you save a Markdown file.
• Format Document — Shift+Alt+F formats all code blocks via VS Code's built-in shortcut.
• Graceful degradation — if a required tool is not available, the extension shows a clear message and skips those blocks without affecting others.

Requirements

Prettier, prettier-plugin-sh, prettier-plugin-sql, js-yaml, postcss, parse5, ESLint, the TypeScript compiler, and @astral-sh/ruff-wasm-nodejs are all bundled — no installation required.

Installation

VS Code Marketplace

Search for Markdown Code Assistant in the Extensions view (Ctrl+Shift+X).

From a .vsix file

code --install-extension md-code-assist-0.1.0.vsix

Commands

Open a Markdown file, then use the Command Palette (Ctrl+Shift+P):

Supported Languages

Prettier (bundled)

VS Code Extensions (auto-installed, no system tools needed)

CLI fallbacks (optional)

If the VS Code extensions above are unavailable, the extension falls back to the system CLI tools if installed:

Configuration

All settings are under mdCodeAssist.* and can be set at User, Workspace, or Folder scope.

Trigger modes

Tip: Prefix any fence with @md-assistant-ignore to permanently exclude a block from all processing: ```python @md-assistant-ignore

Example — format and diagnose on save:

{
  // Format and diagnose every time the file is saved
  "mdCodeAssist.format.triggerMode": "onSave",
  "mdCodeAssist.diagnostics.triggerMode": "onSave"
}

Example — watch mode (format and diagnose as you type):

{
  "mdCodeAssist.format.triggerMode": "onType",
  "mdCodeAssist.diagnostics.triggerMode": "onType"
}

Example — full custom setup:

{
  "mdCodeAssist.format.enabledLanguages": [
    "javascript",
    "typescript",
    "python",
    "json",
    "yaml",
    "html",
    "css",
    "shell",
    "graphql",
    "sql"
  ],
  "mdCodeAssist.diagnostics.enabledLanguages": [
    "javascript",
    "typescript",
    "json",
    "yaml",
    "css",
    "html",
    "shell",
    "python",
    "sql"
  ],
  "mdCodeAssist.format.triggerMode": "onSave",
  "mdCodeAssist.diagnostics.triggerMode": "onSave"
}

Documentation

• Architecture — pipeline diagrams, module layout, design decisions
• Contributing — dev setup, code style, adding formatters, test guidelines

License

MIT