diff --git a/docs/source/markup.rst b/docs/source/markup.rst
index 77eb1d93..d90c529a 100644
--- a/docs/source/markup.rst
+++ b/docs/source/markup.rst
@@ -25,6 +25,16 @@ There is a shorthand for closing a style. If you omit the style name from the cl
     print("[bold red]Bold and red[/] not bold or red")
 
 
+Links
+~~~~~
+
+Console markup can output hyperlinks with the following syntax: ``[link=URL]text[/link]``. Here's an example::
+
+    print("Visit my [link=https://www.willmcgugan.com]blog[/link]!")
+
+If your terminal software supports hyperlinks, you will be able to click the word "blog" which will typically open a browser. If your terminal doesn't support hyperlinks, you will see the text but it won't be clickable.
+
+
 Escaping
 ~~~~~~~~
 
@@ -34,6 +44,7 @@ Occasionally you may want to print something that Rich would interpret as markup
     >>> print("foo[[bar]]")
     foo[bar]
 
+The function :func:`~rich.markup.escape` will handle escape of text for you.
 
 Rendering Markup
 ----------------
diff --git a/docs/source/reference.rst b/docs/source/reference.rst
index 1d5c83bf..95c708b2 100644
--- a/docs/source/reference.rst
+++ b/docs/source/reference.rst
@@ -11,6 +11,7 @@ Reference
    reference/highlighter.rst
    reference/logging.rst
    reference/markdown.rst
+   reference/markup.rst
    reference/measure.rst
    reference/padding.rst
    reference/panel.rst
diff --git a/docs/source/style.rst b/docs/source/style.rst
index 3ceb0efc..3e58c967 100644
--- a/docs/source/style.rst
+++ b/docs/source/style.rst
@@ -55,6 +55,16 @@ Styles may be negated by prefixing the attribute with the word "not". This can b
 
 This will print "foo" and "baz" in bold, but "bar" will be in normal text.
 
+Styles may also have a ``"link"`` attribute, which will turn any styled text in to a *hyperlink* (if supported by your terminal software).
+
+To add a link to a style, the definition should contain the word ``"link"`` followed by a URL. The following example will make a clickable link::
+
+    console.print("Google", style="link https://google.com")
+
+.. note::
+    If you are familiar with HTML you may find applying links in this way a little odd, but the terminal considers a link to be another attribute just like bold, italic etc. 
+    
+
 
 Style Class
 -----------