[formatter] Warn when markdown files are skipped due to preview being disabled

[chinar-amrutkar]

Summary

Fixes #23859

Ruff silently skipped markdown files when preview mode was disabled, leaving users confused about why their files weren't being formatted. Now it emits a warning diagnostic to stderr when markdown files are skipped, making the preview requirement explicit.

Changes

• Partitions format errors into MarkdownExperimental warnings vs other errors
• Renders markdown skip warnings as diagnostics in non-preview check mode
• Other errors continue to use existing diagnostic or simple-message fallback

Test Plan

• Run ruff format on a markdown file without --preview -> warning diagnostic emitted
• Run ruff format --preview on a markdown file -> formats normally, no warning
• Added CLI test covering the warning output

Test Video

Screen.Recording.2026-03-25.at.10.19.41.PM.mov

Edit - added Test Video as requested by @MichaReiser.

[MichaReiser]

I should have made this clearer in #23859, but the issue is specifically about showing a warning in VS Code. I think the behavior in the CLI is fine.

[chinar-amrutkar]

@MichaReiser Thanks for the clarification. I focused on the CLI diagnostic rendering, but I see the real problem is VS Code advertising Ruff as a markdown formatter when preview is disabled.

Should the fix be in the LSP - e.g., not advertising markdown formatting capability when preview is off, or returning a warning via LSP diagnostics when a markdown format request comes in with preview disabled? Or is there a different approach you'd prefer?

Happy to pivot the PR accordingly.

[MichaReiser]

I'm not sure what the best solution is. Mainly because we're limited by what VS Code/LSP support. Figuring out the correct solution requires doing some research on what our options are.

[chinar-amrutkar]

I looked into what VS Code supports for this. The VS Code extension unconditionally registers itself as a markdown formatter via the documentSelector in utilities.ts. In the LSP, format_internal() in format.rs returns Ok(None) when preview is disabled for markdown. VS Code interprets this as "no changes needed" rather than an error.

I have listed some options below based on what I see:

1. window/showMessage from the LSP -- When preview is off and a markdown format request comes in, send a window/showMessage notification ("Markdown formatting requires preview mode") and return Ok(None). Lightweight, gives the user an actionable message. Can be rate-limited to avoid noise on repeated format attempts.
2. Return an error response -- Surface an error to VS Code's formatting API. Most explicit signal, but "formatting failed" might look alarming for what's really a "not enabled yet" situation.
3. Push a diagnostic -- Publish a warning diagnostic on the markdown file. Works, but clutters the Problems panel for something that's more of an informational message.

I think option 1 would be best. It keeps the formatting response contract intact while giving clearly giving the user the specific instructions.

[MichaReiser]

Using showMessage seems reasonable.

[chinar-amrutkar]

I've implemented the window/showMessage approach. When the LSP receives a formatting request for a markdown file with preview disabled, it now sends a warning notification to the editor before returning Ok(None).

The message reads: "Markdown formatting requires preview mode. Enable preview = true in your Ruff configuration."

The CLI diagnostic changes from the previous commit are retained for command-line users.

[MichaReiser]

Thank you.

Would you mind updating your PR summary with a video showing:

• The warning is shown when formatting a file and preview mode is disabled
• The file gets correctly formatted when format.preview is on.

[chinar-amrutkar]

@MichaReiser I have now added a video to the PR summary showing the results of the preview setting on/off.