Warn about layout and asynchronous HTML content
@@ -60,7 +60,16 @@ class Markup(Widget):
'''
text = String(default="", help="""
- The contents of the widget.
+ The text or HTML contents of the widget.
+
+ .. note::
+ If the HTML content contains elements which size depends on
+ on external, asynchronously loaded resources, the size of
+ the widget may be computed incorrectly. This is in particular
+ an issue with images (``<img>``). To remedy this problem, one
+ either has to set explicit dimensions using CSS properties,
+ HTML attributes or model's ``width`` and ``height`` properties,
+ or inline images' contents using data URIs.
""")
style = Dict(String, Any, default={}, help="""
