diff --git a/README.md b/README.md
index 4372840..af094ef 100644
--- a/README.md
+++ b/README.md
@@ -13,27 +13,6 @@ Lua libraries, but may depend on additional system utilities (see widget
 description).
 
 
-## <a name="custom-widget"></a>Custom widget types
-
-Use any of the existing widget types as a starting point for your
-own. Write a quick worker function that does the work and plug it
-in. How data will be formatted, will it be red or blue, should be
-defined in rc.lua (or somewhere else, outside the actual module).
-
-Before writing a widget type you should check if there is already one in the
-contrib directory of Vicious. The contrib directory contains extra widgets you
-can use. Some are for less common hardware, and other were contributed by
-Vicious users. Most of the contrib widgets are obsolete. Contrib widgets will
-not be imported by init unless you explicitly enable it, or load them in your
-rc.lua.
-
-Some users would like to avoid writing new modules. For them Vicious
-kept the old Wicked functionality, possibility to register their own
-functions as widget types. By providing them as the second argument to
-vicious.register. Your function can accept `format` and `warg`
-arguments, just like workers.
-
-
 ## Usage examples
 
 Start with a simple widget, like `date`. Then build your setup from
diff --git a/docs/source/custom.rst b/docs/source/custom.rst
new file mode 100644
index 0000000..6cdcda7
--- /dev/null
+++ b/docs/source/custom.rst
@@ -0,0 +1,22 @@
+.. _custom-wtype:
+
+Custom Widget Types
+===================
+
+Use any of the existing widget types as a starting point for your own.
+Write a quick worker function that does the work and plug it in.
+How data will be formatted, will it be red or blue, should be
+defined in ``rc.lua`` (or somewhere else, outside the actual module).
+
+Before writing a widget type you should check if there is already one
+in the contrib directory of Vicious.  The contrib directory contains
+extra widgets you can use.  Some are for less common hardware, and others
+were contributed by Vicious users.  Most of the contrib widgets are obsolete.
+Contrib widgets will not be imported by init unless you explicitly enable it,
+or load them in your ``rc.lua``.
+
+Some users would like to avoid writing new modules.  For them Vicious kept
+the old Wicked functionality, possibility to register their own functions
+as widget types.  By providing them as the second argument to
+:lua:func:`vicious.register`.  Your function can accept ``format`` and ``warg``
+arguments, just like workers.
diff --git a/docs/source/index.rst b/docs/source/index.rst
index 61328ec..05109a4 100644
--- a/docs/source/index.rst
+++ b/docs/source/index.rst
@@ -21,6 +21,7 @@ Table of Contents
    usage-lua
    usage-awesome
    widgets
+   custom
    caching
    security
    copying
diff --git a/docs/source/usage-awesome.rst b/docs/source/usage-awesome.rst
index 27358e1..0af59d1 100644
--- a/docs/source/usage-awesome.rst
+++ b/docs/source/usage-awesome.rst
@@ -38,7 +38,7 @@ call ``vicious.register`` to register it with Vicious:
         :ref:`provided by Vicious <widgets>` or customly defined.
       * ``function``: custom function from your own
         awesome configuration can be registered as widget types
-        (see [Custom widget types](#custom-widget)).
+        (see :ref:`custom-wtype`).
 
    :param format:
       either of
@@ -120,7 +120,7 @@ vicious.call
         :ref:`provided by Vicious <widgets>` or customly defined.
       * ``function``: custom function from your own
         awesome configuration can be registered as widget types
-        (see [Custom widget types](#custom-widget)).
+        (see :ref:`custom-wtype`).
 
    :param format:
       either of