diff --git a/docs/xml-class.rst b/docs/xml-class.rst
index 9f1ae1364..1f5c688c8 100644
--- a/docs/xml-class.rst
+++ b/docs/xml-class.rst
@@ -103,9 +103,12 @@ There is no need to ever directly construct an :ref:`Xml` object: after creating
        :arg width: if provided, either an absolute (int) value, or a percentage string like "30%". A percentage value refers to the width of the specified ``where`` rectangle in :meth:`Story.place`. If this value is provided and ``height`` is omitted, the image will be included keeping its aspect ratio.
        :arg height: if provided, either an absolute (int) value, or a percentage string like "30%". A percentage value refers to the height of the specified ``where`` rectangle in :meth:`Story.place`. If this value is provided and ``width`` is omitted, the image's aspect ratio will be honored.
 
-    .. method:: add_link(link)
+    .. method:: add_link(href=None, text=None)
 
-       Add an :htmlTag:`a` tag.
+       Add an :htmlTag:`a` tag - inline element, treated like text.
+
+       :arg str href: the URL target.
+       :arg str text: the text to display. If omitted, the ``href`` text is shown instead.
 
     .. method:: add_number_list
 
@@ -113,7 +116,7 @@ There is no need to ever directly construct an :ref:`Xml` object: after creating
 
     .. method:: add_paragraph
 
-       Add a :htmlTag:`p` tag.
+       Add a :htmlTag:`p` tag, context manager.
 
     .. method:: add_span
 
diff --git a/fitz/fitz.i b/fitz/fitz.i
index b639cc0c7..837766641 100644
--- a/fitz/fitz.i
+++ b/fitz/fitz.i
@@ -13122,10 +13122,16 @@ struct Xml
             self.append_child(child)
             return child
 
-        def add_link(self, text=None):
+        def add_link(self, href=None, text=None):
             """Add a hyperlink ("a" tag)"""
             child = self.create_element("a")
-            if type(text) is str:
+            if not isinstance(href, str):
+                href = text
+            if not isinstance(text, str):
+                text = href
+            if href:
+                child.set_attribute("href", href)
+            if text:
                child.append_child(self.create_text_node(text)) 
             prev = self.span_bottom()
             if prev == None: