doc: add guidance for extending built-in formatters (#27)

3 files changed, 23 insertions, 3 deletions

diff --git a/README.md b/README.md
index 470766d..091cdf0 100644
--- a/README.md
+++ b/README.md
@@ -9,6 +9,7 @@ Lightweight yet powerful formatter plugin for Neovim
 - [Setup](#setup)
 - [Formatters](#formatters)
 - [Options](#options)
+- [Customizing formatters](#customizing-formatters)
 - [Autoformat on save](#autoformat-on-save)
 - [API](#api)
   - [format(opts, callback)](#formatopts-callback)
@@ -246,7 +247,7 @@ require("conform").setup({
       -- When false, will create a temp file (will appear in "$FILENAME" args). The temp
       -- file is assumed to be modified in-place by the format command.
       stdin = true,
-      -- A function the calculates the directory to run the command in
+      -- A function that calculates the directory to run the command in
       cwd = require("conform.util").root_file({ ".editorconfig", "package.json" }),
       -- When cwd is not found, don't run the formatter (default false)
       require_cwd = true,
@@ -279,6 +280,25 @@ require("conform").formatters.my_formatter = {
 
 <!-- /OPTIONS -->
 
+## Customizing formatters
+
+If you want to customize how a formatter runs (for example, to pass in environment variables or
+change the command arguments), you can either edit the formatter directly or create one yourself.
+
+```lua
+-- Directly change the values on the built-in configuration
+require("conform.formatters.yamlfix").env = {
+  YAMLFIX_SEQUENCE_STYLE = "block_style",
+}
+
+-- Or create your own formatter that overrides certain values
+require("conform").formatters.yamlfix = vim.tbl_deep_extend("force", require("conform.formatters.yamlfix"), {
+  env = {
+    YAMLFIX_SEQUENCE_STYLE = "block_style",
+  },
+})
+```
+
 ## Autoformat on save
 
 If you want more complex logic than the `format_on_save` option allows, you can write it yourself
diff --git a/doc/conform.txt b/doc/conform.txt
index cc0550b..818a630 100644
--- a/doc/conform.txt
+++ b/doc/conform.txt
@@ -54,7 +54,7 @@ OPTIONS                                                          *conform-option
           -- When false, will create a temp file (will appear in "$FILENAME" args). The temp
           -- file is assumed to be modified in-place by the format command.
           stdin = true,
-          -- A function the calculates the directory to run the command in
+          -- A function that calculates the directory to run the command in
           cwd = require("conform.util").root_file({ ".editorconfig", "package.json" }),
           -- When cwd is not found, don't run the formatter (default false)
           require_cwd = true,
diff --git a/scripts/options_doc.lua b/scripts/options_doc.lua
index 8b1f0d9..a501e38 100644
--- a/scripts/options_doc.lua
+++ b/scripts/options_doc.lua
@@ -40,7 +40,7 @@ require("conform").setup({
       -- When false, will create a temp file (will appear in "$FILENAME" args). The temp
       -- file is assumed to be modified in-place by the format command.
       stdin = true,
-      -- A function the calculates the directory to run the command in
+      -- A function that calculates the directory to run the command in
       cwd = require("conform.util").root_file({ ".editorconfig", "package.json" }),
       -- When cwd is not found, don't run the formatter (default false)
       require_cwd = true,