refactor: deprecate formatter alternation syntax

6 files changed, 20 insertions, 12 deletions

diff --git a/README.md b/README.md
index f5b4258..8583331 100644
--- a/README.md
+++ b/README.md
@@ -129,8 +129,10 @@ require("conform").setup({
     lua = { "stylua" },
     -- Conform will run multiple formatters sequentially
     python = { "isort", "black" },
-    -- Use a sub-list to run only the first available formatter
-    javascript = { { "prettierd", "prettier" } },
+    -- You can customize some of the format options for the filetype (:help conform.format)
+    rust = { "rustfmt", lsp_format = "fallback" },
+    -- Conform will run the first available formatter
+    javascript = { "prettierd", "prettier", stop_after_first = true },
   },
 })
 ```
@@ -457,8 +459,6 @@ require("conform").setup({
     lua = { "stylua" },
     -- Conform will run multiple formatters sequentially
     go = { "goimports", "gofmt" },
-    -- Use a sub-list to run only the first available formatter
-    javascript = { { "prettierd", "prettier" } },
     -- You can also customize some of the format options for the filetype
     rust = { "rustfmt", lsp_format = "fallback" },
     -- You can use a function here to determine the formatters dynamically
diff --git a/doc/conform.txt b/doc/conform.txt
index 589289b..89b5468 100644
--- a/doc/conform.txt
+++ b/doc/conform.txt
@@ -17,8 +17,6 @@ OPTIONS                                                          *conform-option
         lua = { "stylua" },
         -- Conform will run multiple formatters sequentially
         go = { "goimports", "gofmt" },
-        -- Use a sub-list to run only the first available formatter
-        javascript = { { "prettierd", "prettier" } },
         -- You can also customize some of the format options for the filetype
         rust = { "rustfmt", lsp_format = "fallback" },
         -- You can use a function here to determine the formatters dynamically
diff --git a/doc/recipes.md b/doc/recipes.md
index 45c1e07..97c3cdc 100644
--- a/doc/recipes.md
+++ b/doc/recipes.md
@@ -149,7 +149,7 @@ return {
       -- Customize or remove this keymap to your liking
       "<leader>f",
       function()
-        require("conform").format({ async = true, lsp_format = "fallback" })
+        require("conform").format({ async = true })
       end,
       mode = "",
       desc = "Format buffer",
@@ -163,10 +163,14 @@ return {
     formatters_by_ft = {
       lua = { "stylua" },
       python = { "isort", "black" },
-      javascript = { { "prettierd", "prettier" } },
+      javascript = { "prettierd", "prettier", stop_after_first = true },
+    },
+    -- Set default options
+    default_format_opts = {
+      lsp_format = "fallback",
     },
     -- Set up format-on-save
-    format_on_save = { timeout_ms = 500, lsp_format = "fallback" },
+    format_on_save = { timeout_ms = 500 },
     -- Customize formatters
     formatters = {
       shfmt = {
diff --git a/lua/conform/init.lua b/lua/conform/init.lua
index 208edc7..087445b 100644
--- a/lua/conform/init.lua
+++ b/lua/conform/init.lua
@@ -209,6 +209,10 @@ M.list_formatters_for_buffer = function(bufnr)
   local function dedupe_formatters(names, collect)
     for _, name in ipairs(names) do
       if type(name) == "table" then
+        vim.notify_once(
+          "deprecated[conform]: The nested {} syntax to run the first formatter has been replaced by the stop_after_first option. See :help conform.format. Support for the old syntax will be dropped on 2025-01-01.",
+          vim.log.levels.WARN
+        )
         local alternation = {}
         dedupe_formatters(name, alternation)
         if not vim.tbl_isempty(alternation) then
@@ -322,6 +326,10 @@ M.resolve_formatters = function(names, bufnr, warn_on_missing, stop_after_first)
       local info = M.get_formatter_info(name, bufnr)
       add_info(info, warn_on_missing)
     else
+      vim.notify_once(
+        "deprecated[conform]: The nested {} syntax to run the first formatter has been replaced by the stop_after_first option. See :help conform.format. Support for the old syntax will be dropped on 2025-01-01.",
+        vim.log.levels.WARN
+      )
       -- If this is an alternation, take the first one that's available
       for i, v in ipairs(name) do
         local info = M.get_formatter_info(v, bufnr)
diff --git a/lua/conform/types.lua b/lua/conform/types.lua
index 9b775a9..007e84a 100644
--- a/lua/conform/types.lua
+++ b/lua/conform/types.lua
@@ -62,7 +62,7 @@
 
 ---This list of formatters to run for a filetype, an any associated format options.
 ---@class conform.FiletypeFormatterInternal : conform.DefaultFormatOpts
----@field [integer] string|string[]
+---@field [integer] string
 
 ---@alias conform.LspFormatOpts
 ---| '"never"' # never use the LSP for formatting (default)
diff --git a/scripts/options_doc.lua b/scripts/options_doc.lua
index c6d8457..17734d3 100644
--- a/scripts/options_doc.lua
+++ b/scripts/options_doc.lua
@@ -4,8 +4,6 @@ require("conform").setup({
     lua = { "stylua" },
     -- Conform will run multiple formatters sequentially
     go = { "goimports", "gofmt" },
-    -- Use a sub-list to run only the first available formatter
-    javascript = { { "prettierd", "prettier" } },
     -- You can also customize some of the format options for the filetype
     rust = { "rustfmt", lsp_format = "fallback" },
     -- You can use a function here to determine the formatters dynamically