diff --git a/development.ini b/development.ini
--- a/development.ini
+++ b/development.ini
@@ -168,34 +168,44 @@ default_encoding = utf8
 ## issue tracker for Kallithea (leave blank to disable, absent for default)
 #bugtracker = https://bitbucket.org/conservancy/kallithea/issues
 
-## issue tracking mapping for commits messages
-## comment out issue_pat, issue_server, issue_prefix to enable
+## issue tracking mapping for commit messages, comments, PR descriptions, ...
+## Refer to the documentation ("Integration with issue trackers") for more details.
 
-## pattern to get the issues from commit messages
-## default one used here is #<numbers> with a regex passive group for `#`
-## {id} will be all groups matched from this pattern
+## regular expression to match issue references
+## This pattern may/should contain parenthesized groups, that can
+## be referred to in issue_server_link or issue_sub using Python backreferences
+## (e.g. \1, \2, ...). You can also create named groups with '(?P<groupname>)'.
+## To require mandatory whitespace before the issue pattern, use:
+## (?:^|(?<=\s)) before the actual pattern, and for mandatory whitespace
+## behind the issue pattern, use (?:$|(?=\s)) after the actual pattern.
 
 issue_pat = #(\d+)
 
-## server url to the issue, each {id} will be replaced with match
-## fetched from the regex and {repo} is replaced with full repository name
-## including groups {repo_name} is replaced with just name of repo
-
-issue_server_link = https://issues.example.com/{repo}/issue/{id}
+## server url to the issue
+## This pattern may/should contain backreferences to parenthesized groups in issue_pat.
+## A backreference can be \1, \2, ... or \g<groupname> if you specified a named group
+## called 'groupname' in issue_pat.
+## The special token {repo} is replaced with the full repository name
+## including repository groups, while {repo_name} is replaced with just
+## the name of the repository.
 
-## prefix to add to link to indicate it's an url
-## #314 will be replaced by <issue_prefix><id>
+issue_server_link = https://issues.example.com/{repo}/issue/\1
 
-issue_prefix = #
+## substitution pattern to use as the link text
+## If issue_sub is empty, the text matched by issue_pat is retained verbatim
+## for the link text. Otherwise, the link text is that of issue_sub, with any
+## backreferences to groups in issue_pat replaced.
 
-## issue_pat, issue_server_link, issue_prefix can have suffixes to specify
+issue_sub =
+
+## issue_pat, issue_server_link and issue_sub can have suffixes to specify
 ## multiple patterns, to other issues server, wiki or others
 ## below an example how to create a wiki pattern
 # wiki-some-id -> https://wiki.example.com/some-id
 
-#issue_pat_wiki = (?:wiki-)(.+)
-#issue_server_link_wiki = https://wiki.example.com/{id}
-#issue_prefix_wiki = WIKI-
+#issue_pat_wiki = wiki-(\S+)
+#issue_server_link_wiki = https://wiki.example.com/\1
+#issue_sub_wiki = WIKI-\1
 
 ## alternative return HTTP header for failed authentication. Default HTTP
 ## response is 401 HTTPUnauthorized. Currently Mercurial clients have trouble with