diff --git a/doc/usage/index.rst b/doc/usage/index.rst
index 807ab02..e6e97ef 100644
--- a/doc/usage/index.rst
+++ b/doc/usage/index.rst
@@ -49,6 +49,7 @@ Contents:
    project_acls
    roadmap
    flags
+   magic_words
    using_doc
    using_webhooks
    ticket_templates
diff --git a/doc/usage/magic_words.rst b/doc/usage/magic_words.rst
new file mode 100644
index 0000000..3d5a685
--- /dev/null
+++ b/doc/usage/magic_words.rst
@@ -0,0 +1,42 @@
+Magic Words
+===========
+
+Magic words are words and constructs you can use in your commit message to
+make pagure act on tickets or pull-requests.
+
+Enabling magic words
+--------------------
+
+These magic words are enabled if the ``pagure`` git hook is enable. To do
+so, go to your project's ``settings`` page, open the ``Hooks`` tab and
+activate there the ``Pagure`` hook.
+
+
+Using magic words
+-----------------
+
+To reference an issue/PR you need to use one of recognized keywords followed by
+a reference to the issue or PR, separated by whitespace and and optional colon.
+Such references can be either:
+
+- The issue/PR number preceded by the # symbol
+- The full URL of the issue or PR
+
+If using the full URL, it is possible to reference issues in other projects.
+
+The recognized keywords are:
+
+- fix/fixed/fixes
+- relate/related/relates
+- merge/merges/merged
+- close/closes/closed
+
+Examples:
+
+- Fixes #21
+- related: https://pagure.io/myproject/issue/32
+- this commit merges #74
+- Merged: https://pagure.io/myproject/pull-request/74
+
+Capitalization does not matter; neither does the colon (``:``) between
+keyword and number.