diff --git a/.gitignore b/.gitignore
index f69db87ad5a5226535559b6965e771d975ded103..a89ffdab632a2cd881f66cb20e1f154c17cc9387 100644
--- a/.gitignore
+++ b/.gitignore
@@ -26,3 +26,4 @@ xerr.log
 conf/ext
 test/ext
 src/ext
+*~
diff --git a/src/doc/extension/references.rst b/src/doc/extension/references.rst
new file mode 100644
index 0000000000000000000000000000000000000000..63c551612e5e9d807846595b6c5e458bc5096615
--- /dev/null
+++ b/src/doc/extension/references.rst
@@ -0,0 +1,38 @@
+Customizing the display of referenced entities
+=============================================
+
+CaosDB WebUI supports the customized display of referenced entities
+using the :doc:`ext_references <../api/module-resolve_references>`
+module. The ``BUILD_MODULE_EXT_RESOLVE_REFERENCES`` build variable has
+to be set to ``ENABLED`` (see :doc:`/getting_started`) in order to use
+this module.
+
+You may then define your own JavaScript module to define how
+references to specific Records should be resolved. The module has to
+be located at a directory which is known to CaosDB WebUI; we recommend
+``caosdb-webui/src/ext/js``. Set the value of the
+``BUILD_EXT_REFERENCES_CUSTOM_RESOLVER`` build variable to the name of
+this module. The module has to have a ``resolve`` function which takes
+an entity id as its only parameter and returns a ``reference_info``
+object with the resolved custom reference as a ``text`` property. So
+the basic structure of the module should look like
+
+.. code-block:: javascript
+
+   var my_reference_resolver = new function () {
+       // Has to be called ``resolve`` and has to take exactly one
+       // string parameter: the id of the referenced entity.
+       this.resolve = async function (id) {
+	   /*
+	    * find the string that the reference should be resolved to,
+	    * e.g., from the value of the entity's properties.
+	    */
+	   return {"text": new_reference_text}
+       }
+   }
+
+An example is located in
+``caosdb-webui/src/ext/js/person_reference_resolver.js``. It resolves
+any reference to a ``Person`` Record to the value of its ``firstname``
+and ``lastname`` properties separated by a space and is active by
+default.