doc: add additional information about some advanced topics

README.md

@@ -11,6 +11,7 @@ Lightweight yet powerful formatter plugin for Neovim
 - [Formatters](#formatters)
 - [Options](#options)
 - [Recipes](#recipes)
+- [Advanced topics](#advanced-topics)
 - [API](#api)
   - [format(opts, callback)](#formatopts-callback)
   - [list_formatters(bufnr)](#list_formattersbufnr)
@@ -162,6 +163,8 @@ To view configured and available formatters, as well as to see the log file, run
 
 ## Formatters
 
+You can view this list in vim with `:help conform-formatters`
+
 <!-- FORMATTERS -->
 
 - [alejandra](https://kamadorueda.com/alejandra/) - The Uncompromising Nix Code Formatter.
@@ -349,6 +352,16 @@ require("conform").formatters.my_formatter = {
 
 <!-- /RECIPES -->
 
+## Advanced topics
+
+<!-- ADVANCED -->
+
+- [Minimal format diffs](doc/advanced_topics.md#minimal-format-diffs)
+- [Range formatting](doc/advanced_topics.md#range-formatting)
+- [Injected language formatting (code blocks)](doc/advanced_topics.md#injected-language-formatting-code-blocks)
+
+<!-- /ADVANCED -->
+
 ## API
 
 <!-- API -->

doc/advanced_topics.md

@@ -0,0 +1,34 @@
+# Advanced topics
+
+<!-- TOC -->
+
+- [Minimal format diffs](#minimal-format-diffs)
+- [Range formatting](#range-formatting)
+- [Injected language formatting (code blocks)](#injected-language-formatting-code-blocks)
+
+<!-- /TOC -->
+
+## Minimal format diffs
+
+To understand why this is important and why conform.nvim is different we need a bit of historical context. Formatting tools work by taking in the current state of the file and outputting the same contents, with formatting applied. The way most formatting plugins work is they take the new content and replace the entire buffer. The benefit of this approach is that it's very simple. It's easy to code, it's easy to reason about, and it's easy to debug.
+
+What conform does differently is it leverages `:help vim.diff`, Neovim's lua bindings for xdiff. We use this to compare the formatted lines to the original content and calculate minimal chunks where changes need to be applied. From there, we convert these chunks into LSP TextEdit objects and use `vim.lsp.util.apply_text_edits()` to actually apply the changes. Since we're using the built-in LSP utility, we get the benefits of all the work that was put into improving the LSP formatting experience, such as the preservation of extmarks. The piecewise update also does a better job of preserving cursor position, folds, viewport position, etc.
+
+## Range formatting
+
+When a formatting tool doesn't have built-in support for range formatting, conform will attempt to "fake it" when requested. This is necessarily a **best effort** operation and is **not** guaranteed to be correct or error-free, however in _most_ cases it should produce acceptible results.
+
+The way this "aftermarket" range formatting works is conform will format the entire buffer as per usual, but during the diff process it will discard diffs that fall outside of the selected range. This usually approximates a correct result, but as you can guess it's possible for the formatting to exceed the range (if the diff covering the range is large) or for the results to be incorrect (if the formatting changes require two diffs in different locations to be semantically correct).
+
+## Injected language formatting (code blocks)
+
+Sometimes you may have a file that contains small chunks of code in another language. This is most common for markup formats like markdown and neorg, but can theoretically be present in any filetype (for example, embedded SQL queries in a host language). For files like this, it would be nice to be able to format these code chunks using their language-specific formatters.
+
+The way that conform supports this is via the `injected` formatter. If you run this formatter on a file, it will use treesitter to parse out the blocks in the file that have different languages and runs the formatters for that filetype (configured with `formatters_by_ft`). The formatters are run in parallel, one job for each language block.
+
+This formatter is experimental; the behavior and configuration options are still subject to change. Below are the current options available to customize the behavior of the formatter.
+
+```lua
+-- Set this value to true to silence errors when formatting a block fails
+require("conform.formatters.injected").options.ignore_errors = false
+```

scripts/generate.py

@@ -23,6 +23,7 @@
 README = os.path.join(ROOT, "README.md")
 DOC = os.path.join(ROOT, "doc")
 RECIPES = os.path.join(DOC, "recipes.md")
+ADVANCED = os.path.join(DOC, "advanced_topics.md")
 VIMDOC = os.path.join(DOC, "conform.txt")
 OPTIONS = os.path.join(ROOT, "scripts", "options_doc.lua")
 AUTOFORMAT = os.path.join(ROOT, "scripts", "autoformat_doc.lua")
@@ -125,6 +126,13 @@ def update_recipes_toc():
     replace_section(README, r"^<!-- RECIPES -->$", r"^<!-- /RECIPES -->$", subtoc)
 
 
+def update_advanced_toc():
+    toc = ["\n"] + generate_md_toc(ADVANCED) + ["\n"]
+    replace_section(ADVANCED, r"^<!-- TOC -->$", r"^<!-- /TOC -->$", toc)
+    subtoc = add_md_link_path("doc/advanced_topics.md", toc)
+    replace_section(README, r"^<!-- ADVANCED -->$", r"^<!-- /ADVANCED -->$", subtoc)
+
+
 def gen_options_vimdoc() -> VimdocSection:
     section = VimdocSection("Options", "conform-options", ["\n", ">lua\n"])
     with open(OPTIONS, "r", encoding="utf-8") as f:
@@ -178,5 +186,6 @@ def main() -> None:
     update_autocmd_md()
     update_md_api()
     update_recipes_toc()
+    update_advanced_toc()
     update_readme_toc()
     generate_vimdoc()