1 files changed, 49 insertions, 0 deletions
diff --git a/docs/html.rst b/docs/html.rst
new file mode 100644
index 0000000..dec87af
--- /dev/null
+++ b/docs/html.rst
@@ -0,0 +1,49 @@
+.. currentmodule:: markupsafe
+
+HTML Representations
+====================
+
+In many frameworks, if a class implements an ``__html__`` method it
+will be used to get the object's representation in HTML. MarkupSafe's
+:func:`escape` function and :class:`Markup` class understand and
+implement this method. If an object has an ``__html__`` method it will
+be called rather than converting the object to a string, and the result
+will be assumed safe and not escaped.
+
+For example, an ``Image`` class might automatically generate an
+``<img>`` tag:
+
+.. code-block:: python
+
+    class Image:
+        def __init__(self, url):
+            self.url = url
+
+        def __html__(self):
+            return f'<img src="{self.url}">'
+
+.. code-block:: pycon
+
+    >>> img = Image("/static/logo.png")
+    >>> Markup(img)
+    Markup('<img src="/static/logo.png">')
+
+Since this bypasses escaping, you need to be careful about using
+user-provided data in the output. For example, a user's display name
+should still be escaped:
+
+.. code-block:: python
+
+    class User:
+        def __init__(self, id, name):
+            self.id = id
+            self.name = name
+
+        def __html__(self):
+            return f'<a href="/user/{self.id}">{escape(self.name)}</a>'
+
+.. code-block:: pycon
+
+    >>> user = User(3, "<script>")
+    >>> escape(user)
+    Markup('<a href="/users/3">&lt;script&gt;</a>')