diff --git a/README.rst b/README.rst
index c361a56..20e665d 100644
--- a/README.rst
+++ b/README.rst
@@ -114,6 +114,24 @@ saving the page!) by calling ``str()`` on it::
Likewise, use ``unicode(code)`` in Python 2.
+Caveats
+-------
+
+An inherent limitation in wikicode prevents us from generating complete parse
+trees in certain cases. For example, the string ``{{echo|''Hello}}, world!''``
+produces the valid output ``Hello, world!`` in MediaWiki, assuming
+``{{echo}}`` is a template that returns its first parameter. But since
+representing this in mwparserfromhell's node tree would be impossible, we
+compromise by treating the first node (i.e., the template) as plain text,
+parsing only the italics.
+
+The current workaround for cases where you are not interested in text
+formatting is to pass ``skip_style_tags=True`` to ``mwparserfromhell.parse()``.
+This treats ``''`` and ``'''`` like plain text.
+
+A future version of mwparserfromhell will include multiple parsing modes to get
+around this restriction.
+
Integration
-----------
diff --git a/docs/caveats.rst b/docs/caveats.rst
new file mode 100644
index 0000000..927aa54
--- /dev/null
+++ b/docs/caveats.rst
@@ -0,0 +1,17 @@
+Caveats
+=======
+
+An inherent limitation in wikicode prevents us from generating complete parse
+trees in certain cases. For example, the string ``{{echo|''Hello}}, world!''``
+produces the valid output ``Hello, world!`` in MediaWiki, assuming
+``{{echo}}`` is a template that returns its first parameter. But since
+representing this in mwparserfromhell's node tree would be impossible, we
+compromise by treating the first node (i.e., the template) as plain text,
+parsing only the italics.
+
+The current workaround for cases where you are not interested in text
+formatting is to pass *skip_style_tags=True* to :func:`mwparserfromhell.parse`.
+This treats ``''`` and ``'''`` like plain text.
+
+A future version of mwparserfromhell will include multiple parsing modes to get
+around this restriction.
diff --git a/docs/index.rst b/docs/index.rst
index 9a6c8ab..bb00bf6 100644
--- a/docs/index.rst
+++ b/docs/index.rst
@@ -41,6 +41,7 @@ Contents
:maxdepth: 2
usage
+ caveats
integration
changelog
API Reference