[formatter] Warn when markdown files are skipped due to preview being disabled#24150
Conversation
…isabled Previously, ruff format would silently produce an error message via the error log when encountering markdown files without preview mode. This made it easy to miss, especially in editor integrations like VS Code where stderr output is not always visible. Now, markdown formatting errors are rendered as proper warning diagnostics using the same diagnostic rendering pipeline as other format diagnostics. This produces a clear, structured warning with the file location, making it immediately obvious to users that markdown formatting requires preview mode.
|
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. |
|
@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. |
|
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. |
|
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:
I think option 1 would be best. It keeps the formatting response contract intact while giving clearly giving the user the specific instructions. |
|
Using |
…preview mode When the LSP receives a document formatting request for a markdown file and preview mode is disabled, send a notification to the editor before returning Ok(None). This gives VS Code users an actionable message instead of silent no-op behavior. The CLI diagnostic changes from the previous commit are retained for command-line users.
|
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
left a comment
There was a problem hiding this comment.
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.previewis on.
Reverts the format.rs changes per review feedback. The CLI already shows MarkdownExperimental errors via the existing error!() loop. The LSP side shows a proper warning via client.show_message().
|
@MichaReiser I have now added a video to the PR summary showing the results of the preview setting on/off. |
##### [\`v0.15.8\`](https://github.com/astral-sh/ruff/blob/HEAD/CHANGELOG.md#0158) Released on 2026-03-26. ##### Preview features - \[`ruff`] New rule `unnecessary-if` (`RUF050`) ([#24114](astral-sh/ruff#24114)) - \[`ruff`] New rule `useless-finally` (`RUF072`) ([#24165](astral-sh/ruff#24165)) - \[`ruff`] New rule `f-string-percent-format` (`RUF073`): warn when using `%` operator on an f-string ([#24162](astral-sh/ruff#24162)) - \[`pyflakes`] Recognize `frozendict` as a builtin for Python 3.15+ ([#24100](astral-sh/ruff#24100)) ##### Bug fixes - \[`flake8-async`] Use fully-qualified `anyio.lowlevel` import in autofix (`ASYNC115`) ([#24166](astral-sh/ruff#24166)) - \[`flake8-bandit`] Check tuple arguments for partial paths in `S607` ([#24080](astral-sh/ruff#24080)) - \[`pyflakes`] Skip `undefined-name` (`F821`) for conditionally deleted variables ([#24088](astral-sh/ruff#24088)) - `E501`/`W505`/formatter: Exclude nested pragma comments from line width calculation ([#24071](astral-sh/ruff#24071)) - Fix `%foo?` parsing in IPython assignment expressions ([#24152](astral-sh/ruff#24152)) - `analyze graph`: resolve string imports that reference attributes, not just modules ([#24058](astral-sh/ruff#24058)) ##### Rule changes - \[`eradicate`] ignore `ty: ignore` comments in `ERA001` ([#24192](astral-sh/ruff#24192)) - \[`flake8-bandit`] Treat `sys.executable` as trusted input in `S603` ([#24106](astral-sh/ruff#24106)) - \[`flake8-self`] Recognize `Self` annotation and `self` assignment in `SLF001` ([#24144](astral-sh/ruff#24144)) - \[`pyflakes`] `F507`: Fix false negative for non-tuple RHS in `%`-formatting ([#24142](astral-sh/ruff#24142)) - \[`refurb`] Parenthesize generator arguments in `FURB142` fixer ([#24200](astral-sh/ruff#24200)) ##### Performance - Speed up diagnostic rendering ([#24146](astral-sh/ruff#24146)) ##### Server - Warn when Markdown files are skipped due to preview being disabled ([#24150](astral-sh/ruff#24150)) ##### Documentation - Clarify `extend-ignore` and `extend-select` settings documentation ([#24064](astral-sh/ruff#24064)) - Mention AI policy in PR template ([#24198](astral-sh/ruff#24198)) ##### Other changes - Use trusted publishing for NPM packages ([#24171](astral-sh/ruff#24171)) ##### Contributors - [@bitloi](https://github.com/bitloi) - [@Sim-hu](https://github.com/Sim-hu) - [@mvanhorn](https://github.com/mvanhorn) - [@chinar-amrutkar](https://github.com/chinar-amrutkar) - [@markjm](https://github.com/markjm) - [@RenzoMXD](https://github.com/RenzoMXD) - [@vivekkhimani](https://github.com/vivekkhimani) - [@seroperson](https://github.com/seroperson) - [@moktamd](https://github.com/moktamd) - [@charliermarsh](https://github.com/charliermarsh) - [@ntBre](https://github.com/ntBre) - [@zanieb](https://github.com/zanieb) - [@dylwil3](https://github.com/dylwil3) - [@MichaReiser](https://github.com/MichaReiser) Renovate-Branch: renovate/2024.6-ruff-0.15.x Change-Id: Ifd4216a963962ffb24a4df69802bc60fcc29628d Priv-Id: 46d2f61be3a5e65a9fdd2fef998ba41ea3388f12
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
MarkdownExperimentalwarnings vs other errorsTest Plan
ruff formaton a markdown file without--preview-> warning diagnostic emittedruff format --previewon a markdown file -> formats normally, no warningTest Video
Screen.Recording.2026-03-25.at.10.19.41.PM.mov
Edit - added Test Video as requested by @MichaReiser.