diff --git a/docs/contribute/documenting-code.rst b/docs/contribute/documenting-code.rst
index 228ff74b58..5352a3bc86 100644
--- a/docs/contribute/documenting-code.rst
+++ b/docs/contribute/documenting-code.rst
@@ -153,6 +153,16 @@ The following roles are provided:
 - ``:example_file:`path``` - points to file inside ESP-IDF examples dir
 - ``:example_raw:`path``` - points to raw view of the file inside ESP-IDF examples dir
 
+Example implementation::
+
+    * :example:`get-started/hello_world`
+    * :example:`Hello World! <get-started/hello_world>`
+
+How it renders:
+
+* :example:`get-started/hello_world`
+* :example:`Hello World! <get-started/hello_world>`
+
 A check is added to the CI build script, which searches RST files for presence of hard-coded links (identified by tree/master, blob/master, or raw/master part of the URL). This check can be run manually: ``cd docs`` and then ``make gh-linkcheck``.
 
 .. _add-illustrations:
@@ -248,7 +258,7 @@ Installation of Doxygen is OS dependent:
 
 .. note::
 
-    If you are installing on Windows system (Linux and MacOS users should skip this note), **before** going further, execute two extra steps below. These steps are required for the :ref:`blockdiag <add-illustrations>` to install:
+    If you are installing on Windows system (Linux and MacOS users should skip this note), **before** going further, execute two extra steps below. These steps are required to install dependencies of "blockdiag" discussed under :ref:`add-illustrations`.
 
     1.  Update all the system packages:
 
diff --git a/docs/link-roles.py b/docs/link-roles.py
index a7d549e827..a9e45145ec 100644
--- a/docs/link-roles.py
+++ b/docs/link-roles.py
@@ -1,5 +1,6 @@
 # based on http://protips.readthedocs.io/link-roles.html
 
+import re
 from docutils import nodes
 from repo_util import run_cmd_get_output
 
@@ -28,7 +29,14 @@ def setup(app):
 
 def autolink(pattern):
     def role(name, rawtext, text, lineno, inliner, options={}, content=[]):
-        url = pattern % (text,)
-        node = nodes.reference(rawtext, text, refuri=url, **options)
+        m = re.search('(.*)\s*<(.*)>', text)
+        if m:
+            link_text = m.group(1)
+            link = m.group(2)
+        else:
+            link_text = text
+            link = text
+        url = pattern % (link,)
+        node = nodes.reference(rawtext, link_text, refuri=url, **options)
         return [node], []
     return role