diff --git a/RELEASE_GUIDELINES.md b/RELEASE_GUIDELINES.md
index 5d89ceec00bbd8ba228bb497964f0eeb437891f7..5c1fd68d462212e9b81dbc803fc590006df36a3d 100644
--- a/RELEASE_GUIDELINES.md
+++ b/RELEASE_GUIDELINES.md
@@ -21,13 +21,13 @@ guidelines of the CaosDB Project
 3. Update the version property in [pom.xml](./pom.xml) (probably this means to
    remove the `-SNAPSHOT`) and in `src/doc/conf.py`.
 
-4. Merge the release branch into the master branch.
+4. Merge the release branch into the main branch.
 
-5. Tag the latest commit of the master branch with `v<VERSION>`.
+5. Tag the latest commit of the main branch with `v<VERSION>`.
 
 6. Delete the release branch.
 
-7. Merge the master branch back into the dev branch.
+7. Merge the main branch back into the dev branch.
 
 8. Update the version property in [pom.xml](./pom.xml) for the next
    developlement round (with a `-SNAPSHOT` suffix).
diff --git a/src/doc/Permissions.rst b/src/doc/Permissions.rst
index c624092aff4f479bc8ed48f439109530cc5295aa..a5fae0bbfaf8d021691f7f8af93c3db9b5995497 100644
--- a/src/doc/Permissions.rst
+++ b/src/doc/Permissions.rst
@@ -28,7 +28,7 @@ A Permission Rule consists of:
 
 -  A type: Permission Rules can be of ``Grant`` or ``Deny`` type, either
    granting or denying specific permissions.
--  A `role <manuals/general/roles>`__ (or user): For which users the
+-  A :doc:`role <roles>` (or user): For which users the
    permission shall be granted or denied.
 -  A permission action: Which action shall be permitted or forbidden,
    for example all retrieval, or modifications of a specific entity.
diff --git a/src/doc/conf.py b/src/doc/conf.py
index fb3d6264cc4add018b83d08378813aab9d10964d..7b6ac359abf8d88d3c60cb37001bc43e00b97872 100644
--- a/src/doc/conf.py
+++ b/src/doc/conf.py
@@ -55,8 +55,8 @@ templates_path = ['_templates']
 # The suffix(es) of source filenames.
 # You can specify multiple suffix as a list of string:
 #
-# source_suffix = ['.rst', '.md']
-source_suffix = '.rst'
+source_suffix = ['.rst', '.md']
+# source_suffix = '.rst'
 
 # The master toctree document.
 master_doc = 'index'
diff --git a/src/doc/roles.md b/src/doc/roles.md
index 80729fb11f8113c64da7e9bf26b04de68fdd6681..b70f54506e8adb3ad3caf46af94479af49370409 100644
--- a/src/doc/roles.md
+++ b/src/doc/roles.md
@@ -10,7 +10,7 @@ users may have the same role, and there may be roles without any users.
 
 The user and their roles are always returned by the server in answers to requests
 and can thus be interpreted and used by clients.  The most important use though
-is [permission](manuals/general/permissions) checking in the server: Access and
+is [permission](permissions) checking in the server: Access and
 modification of
 entities can be controlled via roles, so that users of a given role are allowed
 or denied certain actions.  Incidentally, the permission to edit the permissions
@@ -32,4 +32,4 @@ There are some special roles, which are automatically assigned to users:
 
 Except for the `anonymous` role, these special roles are not returned by the
 server, but can nevertheless be used to define
-[permissions](manuals/general/permissions).
+[permissions](permissions.rst).