service/documentation.md

@@ -136,6 +136,24 @@ ${GIT_DIR:-.git}/../bin/mdl-wrapper $(git diff --cached --name-only HEAD)
 ${GIT_DIR:-.git}/../bin/mdl-wrapper $(git diff-tree --no-commit-id --name-only -r HEAD)
 ```
 
+If you have a document you cannot commit because it has too many
+errors, you may be able to convert the whole file at once with a
+formatter, including:
+
+ * [prettier](https://prettier.io/) - multi-format, node/javascript, not in Debian
+ * [mdformat](https://github.com/executablebooks/mdformat/) - markdown-only, Python, very opiniated, [soon in
+   Debian](https://bugs.debian.org/cgi-bin/bugreport.cgi?bug=1042062)
+ * [pandoc](https://pandoc.org/) - multi-format document converter, Haskell, widely
+   packaged
+
+Pandoc, in particular, is especially powerful as it has many flags to
+control output. This might work for most purposes, including turning
+all inline links to references:
+
+    pandoc --from markdown --to commonmark+smart \
+      --reference-links --reference-location=section \
+      foo.md | sponge foo.md
+
 ### Spell checking
 
 The [codespell][] program checks for spelling mistakes in CI. If you