Add custom-writers.md.

2 files changed, 55 insertions, 4 deletions

diff --git a/changelog.md b/changelog.md
index 967206850..bf054806c 100644
--- a/changelog.md
+++ b/changelog.md
@@ -1,4 +1,4 @@
-# Revision history for pandoc
+## Revision history for pandoc
 
 ## pandoc 2.16.2 (2021-11-21)
 
@@ -147,13 +147,16 @@
   * Require Cabal 2.4.  Use wildcards to ensure that all pptx tests are
     included (#7677).
 
-  * Update bash_completion.tpl (S.P.H.).
+  * Update `bash_completion.tpl` (S.P.H.).
 
   * Add `data/creole.lua` as sample custom reader.
 
-  * Add `doc/custom-readers.md`.
+  * Add `doc/custom-readers.md` and `doc/custom-writers.md`.
 
-  * MANUAL.txt: update table of exit codes and corresponding errors
+  * `doc/lua-filters.md`: add section on global modules, including lpeg
+    (Albert Krewinkel).
+
+  * `MANUAL.txt`: update table of exit codes and corresponding errors
     (Albert Krewinkel).
 
   * Use latest texmath.
diff --git a/doc/custom-writers.md b/doc/custom-writers.md
new file mode 100644
index 000000000..b2258a95f
--- /dev/null
+++ b/doc/custom-writers.md
@@ -0,0 +1,48 @@
+---
+author:
+- John MacFarlane
+date: 'November 21, 2021'
+title: Creating Custom Pandoc Writers in Lua
+---
+
+# Introduction
+
+If you need to render a format not already handled by pandoc,
+or you want to change how pandoc renders a format,
+you can create a custom writer using the [Lua] language.
+Pandoc has a built-in Lua interpreter, so you needn't
+install any additional software to do this.
+
+[Lua]: https://www.lua.org
+
+A custom writer is a Lua file that defines functions for
+rendering each element of a pandoc AST.
+
+For example,
+
+``` lua
+function Para(s)
+  return "<paragraph>" .. s .. "</paragraph>"
+end
+```
+
+The best way to go about creating a custom writer is to modify
+the example that comes with pandoc.  To get the example, you
+can do
+
+```
+pandoc --print-default-data-file sample.lua > sample.lua
+```
+
+`sample.lua` is a full-features HTML writer, with explanatory
+comments. To use it, just use the path to the custom writer as
+the writer name:
+
+```
+pandoc -t sample.lua myfile.md
+```
+
+`sample.lua` defines all the functions needed by any custom
+writer, so you can design your own custom writer by modifying
+the functions in `sample.lua` according to your needs.
+