diff --git a/docs/conf.py b/docs/conf.py
index 9883b6fc5..72cce2ba7 100644
--- a/docs/conf.py
+++ b/docs/conf.py
@@ -17,6 +17,7 @@ from sphinx import addnodes
 from sphinx.util.logging import getLogger
 
 
+# config {{{
 # -- Project information -----------------------------------------------------
 
 project = 'kitty'
@@ -74,7 +75,6 @@ exclude_patterns = ['_build', 'Thumbs.db',
 pygments_style = 'sphinx'
 
 rst_prolog = '''
-.. |kitty.conf| replace:: :doc:`kitty.conf </conf>`
 .. |kitty| replace:: *kitty*
 .. role:: green
 .. role:: italic
@@ -193,6 +193,7 @@ texinfo_documents = [
      author, 'kitty', 'One line description of project.',
      'Miscellaneous'),
 ]
+# }}}
 
 
 # GitHub linking inlne roles {{{
@@ -356,6 +357,8 @@ def render_conf(conf_name, all_options):
     kitty_mod = 'kitty_mod'
 
     def render_group(group):
+        a('')
+        a(f'.. _conf-{conf_name}-{group.name}:')
         a('')
         a(group.short_text)
         heading_level = '+' if '.' in group.name else '^'
diff --git a/docs/index.rst b/docs/index.rst
index b6cf97e22..b04774503 100644
--- a/docs/index.rst
+++ b/docs/index.rst
@@ -192,7 +192,7 @@ Currently, there are five layouts available,
 
 You can switch between layouts using the :sc:`next_layout` key combination. You can
 also create shortcuts to select particular layouts, and choose which layouts
-you want to enable/disable, see |kitty.conf| for examples.
+you want to enable/disable, see :ref:`conf-kitty-shortcuts.layout` for examples.
 
 You can resize windows inside layouts. Press :sc:`start_resizing_window` to
 enter resizing mode and follow the on-screen instructions.  In a given window
@@ -203,7 +203,7 @@ but a row/column in the layout, all windows in that row/column will be resized.
 
 Some layouts take options to control their behavior. For example, the ``fat``
 and ``tall`` layouts accept the ``bias`` option to control how the available
-space is split up. To specify the option, in |kitty.conf| use::
+space is split up. To specify the option, in :opt:`kitty.conf <enabled_layouts>` use::
 
     enabled_layouts tall:bias=70
 
@@ -301,7 +301,8 @@ specify individual families for the regular, bold, italic and bold+italic
 fonts. You can even specify specific font families for specific ranges of
 unicode characters. This allows precise control over text rendering. It can
 come in handy for applications like powerline, without the need to use patched
-fonts. See the various font related configuration directives in |kitty.conf|.
+fonts. See the various font related configuration directives in
+:ref:`conf-kitty-fonts`.
 
 
 .. _scrollback:
diff --git a/docs/remote-control.rst b/docs/remote-control.rst
index 7ddb05aa2..dc813e933 100644
--- a/docs/remote-control.rst
+++ b/docs/remote-control.rst
@@ -16,8 +16,8 @@ Start by running |kitty| as::
 
     kitty -o allow_remote_control=yes --window-layout tall
 
-In order for control to work, ``allow_remote_control`` must be enabled in
-|kitty.conf|. Here we turn it on explicitly at the command line.
+In order for control to work, :opt:`allow_remote_control` must be enabled in
+:file:`kitty.conf`. Here we turn it on explicitly at the command line.
 
 Now, in the new |kitty| window, enter the command::
 
diff --git a/kitty/cli.py b/kitty/cli.py
index a07efa7d4..8a2888179 100644
--- a/kitty/cli.py
+++ b/kitty/cli.py
@@ -98,7 +98,7 @@ messages. For example, :option:`{appname} --listen-on`=unix:/tmp/mykitty or
 UNIX sockets, not associated with a file, like this: :option:`{appname} --listen-on`=unix:@mykitty.
 To control kitty, you can send it commands with :italic:`kitty @` using the :option:`kitty @ --to` option
 to specify this address. Note that this option will be ignored, unless you set
-:italic:`allow_remote_control` to yes in |kitty.conf|.
+:opt:`allow_remote_control` to yes in :file:`kitty.conf`.
 
 
 # Debugging options
@@ -189,6 +189,10 @@ def title(x):
     return blue(bold(x))
 
 
+def opt(text):
+    return text
+
+
 def option(x):
     idx = x.find('-')
     if idx > -1:
@@ -271,7 +275,7 @@ def prettify(text):
         return role_map[role](text)
 
     text = re.sub(r':([a-z]+):`([^`]+)`', sub, text)
-    return text.replace('|kitty.conf|', italic('kitty.conf'))
+    return text
 
 
 def prettify_rst(text):
diff --git a/kitty/cmds.py b/kitty/cmds.py
index 1d11c9722..76d64f3e9 100644
--- a/kitty/cmds.py
+++ b/kitty/cmds.py
@@ -607,7 +607,7 @@ def set_colors(boss, window, payload):
 @cmd(
     'Set the background_opacity',
     'Set the background opacity for the specified windows. This will only work if you have turned on'
-    ' dynamic_background_opacity in kitty.conf. The background opacity affects all kitty windows in a'
+    ' :opt:`dynamic_background_opacity` in :file:`kitty.conf`. The background opacity affects all kitty windows in a'
     ' single os_window. For example: kitty @ set-background-opacity 0.5',
     options_spec='''\
 --all -a
diff --git a/kitty/remote_control.py b/kitty/remote_control.py
index 3c20543da..77d88c9e9 100644
--- a/kitty/remote_control.py
+++ b/kitty/remote_control.py
@@ -85,8 +85,8 @@ def do_io(to, send, no_response):
 
 all_commands = tuple(sorted(cmap))
 cli_msg = (
-        'Control {appname} by sending it commands. Add'
-        ' :italic:`allow_remote_control yes` to |kitty.conf| for this'
+        'Control {appname} by sending it commands. Set the'
+        ' :opt:`allow_remote_control` option to yes in :file:`kitty.conf` for this'
         ' to work.'
 ).format(appname=appname)