docs: FAQ entry for Markdown engines (#454)

Author: hukkin

README.md

@@ -137,6 +137,24 @@ Here's a few pointers to get you started:
 
 ## Frequently Asked Questions
 
+### Why does mdformat backslash escape special syntax specific to MkDocs / Hugo / Obsidian / GitHub / some other Markdown engine?
+
+Mdformat is a CommonMark formatter.
+It doesn't have out-of-the-box support for syntax other than what is defined in [the CommonMark specification](https://spec.commonmark.org/current/).
+
+The custom syntax that these Markdown engines introduce typically reinvents the meaning of
+angle brackets, square brackets, parentheses, hash characters — characters that have a special meaning in CommonMark.
+Mdformat often resorts to backslash escaping these characters to ensure the formatting changes it makes never alters a rendered document.
+
+Additionally some engines, namely MkDocs, [do not support](https://github.com/mkdocs/mkdocs/issues/1835) CommonMark to begin, so incompatibilities are unavoidable.
+
+Luckily mdformat is extensible by plugins.
+For many Markdown engines you'll find support by searching
+[the plugin docs](https://mdformat.readthedocs.io/en/stable/users/plugins.html)
+or [mdformat GitHub topic](https://github.com/topics/mdformat).
+
+You may also want to consider a documentation engine that adheres to CommonMark as its base syntax e.g. [mdBook](https://rust-lang.github.io/mdBook/) or [Sphinx with Markdown](https://www.sphinx-doc.org/en/master/usage/markdown.html).
+
 ### Why not use [Prettier](https://github.com/prettier/prettier) instead?
 
 Mdformat is pure Python code!
@@ -157,10 +175,10 @@ according to the author themselves,
 is [inferior to markdown-it](https://github.com/remarkjs/remark/issues/75#issuecomment-143532326) used by mdformat.
 `remark-parse` v9.x is advertised as CommonMark compliant
 and presumably would fix many of the issues,
-but is not used by Prettier (v2.4.0) yet.
+but is not used by Prettier (v3.3.3) yet.
 
-Prettier (v2.4.0), being able to format many languages other than Markdown,
-is a large package with 65 direct dependencies
+Prettier (v3.3.3), being able to format many languages other than Markdown,
+is a large package with 73 direct dependencies
 (mdformat only has one in Python 3.11+).
 This can be a disadvantage in many environments,
 one example being size optimized Docker images.

docs/contributors/contributing.md

@@ -125,4 +125,4 @@ If using Poetry or Flit for packaging, the entry point configuration in `pyproje
 
 ## Making your plugin discoverable
 
-In case you host your plugin on GitHub, make sure to add it under the "mdformat" topic so it shows up on https://github.com/topics/mdformat.
+In case you host your plugin on GitHub, make sure to add it under the "mdformat" topic so it shows up on <https://github.com/topics/mdformat>.

docs/users/plugins.md

@@ -23,7 +23,7 @@ formatted = mdformat.text(unformatted, codeformatters={"python"})
 assert formatted == '```python\n"""black converts quotes"""\n```\n'
 ````
 
-### Existing plugins (see https://github.com/topics/mdformat for more!)
+### Existing plugins (more on [GitHub](https://github.com/topics/mdformat))
 
 <table>
   <tr>
@@ -90,7 +90,7 @@ unformatted = "content...\n"
 formatted = mdformat.text(unformatted, extensions={"tables"})
 ```
 
-### Existing plugins (see https://github.com/topics/mdformat for more!)
+### Existing plugins (more on [GitHub](https://github.com/topics/mdformat))
 
 <table>
   <tr>
@@ -154,7 +154,7 @@ formatted = mdformat.text(unformatted, extensions={"tables"})
 
 Other plugins that don't fit the above categories.
 
-### Existing plugins
+### Existing plugins (more on [GitHub](https://github.com/topics/mdformat))
 
 <table>
   <tr>