From 1a4202d5fa50e1cf140ccced82e4cce6242fa35d Mon Sep 17 00:00:00 2001
From: Steven Arcangeli <stevearc@stevearc.com>
Date: Wed, 6 Sep 2023 14:01:00 -0700
Subject: doc: add guidance for extending built-in formatters (#27)

---
 README.md               | 22 +++++++++++++++++++++-
 doc/conform.txt         |  2 +-
 scripts/options_doc.lua |  2 +-
 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,
-- 
cgit v1.2.3-70-g09d2