doc: add recipe for command to run tweaked formatter

Author: stevearc

README.md

@@ -524,6 +524,7 @@ The following magic strings are available in `args` and `range_args`. They will
 - [Lazy loading with lazy.nvim](doc/recipes.md#lazy-loading-with-lazynvim)
 - [Leave visual mode after range format](doc/recipes.md#leave-visual-mode-after-range-format)
 - [Run the first available formatter followed by more formatters](doc/recipes.md#run-the-first-available-formatter-followed-by-more-formatters)
+- [Create a separate command to do special formatting you don't want to happen on save](doc/recipes.md#create-a-separate-command-to-do-special-formatting-you-dont-want-to-happen-on-save)
 
 <!-- /RECIPES -->
 

doc/recipes.md

@@ -9,6 +9,7 @@
 - [Lazy loading with lazy.nvim](#lazy-loading-with-lazynvim)
 - [Leave visual mode after range format](#leave-visual-mode-after-range-format)
 - [Run the first available formatter followed by more formatters](#run-the-first-available-formatter-followed-by-more-formatters)
+- [Create a separate command to do special formatting you don't want to happen on save](#create-a-separate-command-to-do-special-formatting-you-dont-want-to-happen-on-save)
 
 <!-- /TOC -->
 
@@ -114,30 +115,30 @@ You can run LSP commands before formatting a file. This example uses the `ts_ls`
 
 ```lua
 vim.api.nvim_create_autocmd("BufWritePre", {
-	desc = "Format before save",
-	pattern = "*",
-	group = vim.api.nvim_create_augroup("FormatConfig", { clear = true }),
-	callback = function(ev)
-        local conform_opts = { bufnr = ev.buf, lsp_format = "fallback", timeout_ms = 2000 }
-        local client = vim.lsp.get_clients({ name = "ts_ls", bufnr = ev.buf })[1]
-
-        if not client then
-            require("conform").format(conform_opts)
-            return
-        end
-
-        local request_result = client:request_sync("workspace/executeCommand", {
-            command = "_typescript.organizeImports",
-            arguments = { vim.api.nvim_buf_get_name(ev.buf) },
-        })
-
-        if request_result and request_result.err then
-            vim.notify(request_result.err.message, vim.log.levels.ERROR)
-            return
-        end
-
-        require("conform").format(conform_opts)
-    end,
+  desc = "Format before save",
+  pattern = "*",
+  group = vim.api.nvim_create_augroup("FormatConfig", { clear = true }),
+  callback = function(ev)
+    local conform_opts = { bufnr = ev.buf, lsp_format = "fallback", timeout_ms = 2000 }
+    local client = vim.lsp.get_clients({ name = "ts_ls", bufnr = ev.buf })[1]
+
+    if not client then
+      require("conform").format(conform_opts)
+      return
+    end
+
+    local request_result = client:request_sync("workspace/executeCommand", {
+      command = "_typescript.organizeImports",
+      arguments = { vim.api.nvim_buf_get_name(ev.buf) },
+    })
+
+    if request_result and request_result.err then
+      vim.notify(request_result.err.message, vim.log.levels.ERROR)
+      return
+    end
+
+    require("conform").format(conform_opts)
+  end,
 })
 ```
 
@@ -238,3 +239,29 @@ require("conform").setup({
   },
 })
 ```
+
+## Create a separate command to do special formatting you don't want to happen on save
+
+Some formatters have multiple modes, or perform some operations that you don't want to happen on
+every save, but you do want to run them on-demand. For these, you can declare them as a separate
+formatter and create a keymap that invokes it directly. In this example, we will use
+`gdscript-formatter` to format on save and have a special keymap to use it to reorder code.
+
+```lua
+require("conform").setup({
+  formatters_by_ft = {
+    gdscript = { "gdscript-formatter" },
+  },
+  formatters = {
+    ["gdscript-reorder"] = {
+      inherit = "gdscript-formatter",
+      prepend_args = { "--reorder-code" },
+    },
+  },
+  format_on_save = {},
+})
+
+vim.keymap.set("n", "<leader>fo", function()
+  require("conform").format({ formatters = { "gdscript-reorder" } })
+end, { desc = "[F]ormat Re[O]rder" })
+```