Fixes #360 - Create/consolidate aliases for all documentation parts for better linking.

Author: dvuckovic

.rstcheck.cfg

@@ -2,5 +2,8 @@
 report_level=WARNING
 ignore_directives =
   tabs
+ignore_roles=
+  admin-docs,
+  user-docs
 ignore_languages=
   json

admin/console/dangerzone-for-experts.rst

@@ -41,10 +41,8 @@ Removing users
    If you're not sure what to do and need to learn more about what Zammad does
    upon removing users, please consider using Zammad's UI options in stead.
 
-   Our documentation for the `data privacy`_ function will help you a lot!
-
-.. _data privacy:
-   https://admin-docs.zammad.org/en/latest/system/data-privacy.html
+   Our documentation for the :admin-docs:`data privacy </system/data-privacy.html>`
+   function will help you a lot!
 
 Removing users is possible in 2 ways: A single user and in bulk.
 

admin/console/working-on-ticket-articles.rst

@@ -6,23 +6,16 @@ Working with ticket articles
 Count Public “Notes” toward SLAs
 --------------------------------
 
-Normally, `notes`_ don't count toward `service-level agreements`_.
+Normally, :user-docs:`notes </basics/service-ticket/follow-up.html#adding-new-messages-notes>`
+don't count toward :admin-docs:`service-level agreements </manage/slas/index.html>`.
 Use the following command to include publicly-visible notes when tracking SLA
 compliance. (Internal notes *will never* affect SLA calculations.)
 
-.. _notes:
-   https://user-docs.zammad.org/en/latest/basics/service-ticket/follow-up.html#adding-new-messages-notes
-
-.. _service-level agreements:
-   https://admin-docs.zammad.org/en/latest/manage/slas.html
-
 .. note::
 
    By default, customers are not notified when public notes are added to a
-   ticket. Set up a `trigger`_ if you wish to change this behavior. 
-
-.. _trigger:
-   https://admin-docs.zammad.org/en/latest/manage/trigger.html
+   ticket. Set up a :admin-docs:`trigger </manage/trigger.html>` if you wish to
+   change this behavior.
 
 .. warning::
 

admin/console/working-on-tickets.rst

@@ -116,10 +116,8 @@ This will show all state types needed for creating new ticket states.
    *pending reminders* or *closed* states.
 
    State types also indicate the color scheme to be used.
-   You can learn more about that `in our user documentation`_.
-
-.. _in our user documentation:
-   https://user-docs.zammad.org/en/latest/basics/service-ticket/settings/state.html
+   You can learn more about that
+   :user-docs:`in our user documentation </basics/service-ticket/settings/state.html>`.
 
 .. code-block:: ruby
 
@@ -193,9 +191,10 @@ reached.
 (optional) Disable date and time picker (pending till) for pending states
 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 
-Starting with Zammad 5.0, `Core Workflows`_ automatically handles displaying the
-"pending till" field for pending states. Below snippet *is not required* and is
-only relevant if you don't want to create a workflow within the UI of Zammad.
+Starting with Zammad 5.0, :admin-docs:`Core Workflows </system/core-workflows.html>`
+automatically handles displaying the "pending till" field for pending states.
+Below snippet *is not required* and is only relevant if you don't want to
+create a workflow within the UI of Zammad.
 
 Replace ``pending customer feedback`` with the pending state of your choice.
 
@@ -242,11 +241,9 @@ Limit available states for customers
 
 .. tip::
 
-   `Core Workflows`_ allows you to achieve below described behavior any time
-   without any issues. No need to use the console if you don't want to!
-
-.. _Core Workflows:
-   https://admin-docs.zammad.org/en/latest/system/core-workflows.html
+   :admin-docs:`Core Workflows </system/core-workflows.html>` allows you to
+   achieve below described behavior any time without any issues. No need to use
+   the console if you don't want to!
 
 By default Zammad allows customers to change Ticket states to ``open`` and
 ``closed``. If this does not meet your requirenments, you can adjust this at

admin/console/working-on-users.rst

@@ -21,10 +21,8 @@ Unlock a locked user account
 .. tip::
 
    Unlocking a locked user account is also supported by Zammad's web UI.
-   Please refer the `admin documentation`_ for more information.
-
-.. _admin documentation:
-   https://admin-docs.zammad.org/en/latest/manage/users/via-the-admin-panel.html
+   Please refer to the :admin-docs:`admin documentation </manage/users/via-the-admin-panel.html>`
+   for more information.
 
 It sometimes happens that a user locks himself out by wildly trying the wrong
 password multiple times. Depending on your maximum failing login count

api/generic-cti/index.rst

@@ -7,16 +7,15 @@ Features
    Here's a small condensed list of the possibilities this CTI API provides.
 
    Inbound
-      * `Caller log functions`_ for your agents.
+      * :user-docs:`Caller log functions </extras/caller-log.html>` for your
+        agents.
       * Blocking of CallerIDs during signaling. *
-   
+
    Outbound
-      * `Caller log functions`_ for your agents.
+      * :user-docs:`Caller log functions </extras/caller-log.html>` for your
+        agents.
       * Set outbound caller IDs depending on the caller ID target.
 
-.. _Caller log functions:
-   https://user-docs.zammad.org/en/latest/extras/caller-log.html
-
 .. include:: /api/generic-cti/cti-endpoint-limitations.include.rst
 
 Endpoint
@@ -28,16 +27,13 @@ Endpoint
 
          Generic CTI configuration and the correct endpoint can be found in your
          Zammad integration settings and are documented in our
-         `admin documentation`_.
+         :admin-docs:`admin documentation </system/integrations/cti/generic.html>`.
 
          | Please also note the there listed requirements and limitations.
          | All options that require returns (e.g. blocking, manipulating
            outgoing caller IDs) rely on configurations within the Zammad CTI
            integration page.
 
-.. _admin documentation:
-   https://admin-docs.zammad.org/en/latest/system/integrations/generic-cti.html
-
 Events
    There are several events in terms of an ongoing call.
    These actions always come from your PBX system and may be:

api/generic-cti/newcall-event.rst

@@ -42,10 +42,7 @@ New call
    * - ``queue``
      - e.g. ``support``, ``sales``
      - An optional queue name, this option is relevant for the
-       `Caller Log Filter <admin documentation>`_
-
-.. _admin documentation:
-   https://admin-docs.zammad.org/en/latest/system/integrations/generic-cti.html
+       :admin-docs:`Caller Log Filter </system/integrations/cti/generic.html>`
 
 There's two options on how to ``POST`` the relevant data to Zammad.
 

api/intro.rst

@@ -550,10 +550,8 @@ and user each.
 .. warning::
 
    Please note that Core Workflows may restrict access to attributes or values.
-   see `Core Workflows limitations`_ to learn more.
-
-.. _Core Workflows limitations:
-   https://admin-docs.zammad.org/en/latest/system/core-workflows/limitations.html
+   See :admin-docs:`Core Workflows limitations </system/core-workflows/limitations.html>`
+   to learn more.
 
 Pagination
 ==========

api/object.rst

@@ -7,11 +7,8 @@ Object
    Proceed with absolute caution and ensure to adjust any of Zammads default
    fields.
 
-   If you want to hide fields, consider `Core Workflows`_ instead.
-   For states and priorities use either API endpoints or rails console.
-
-.. _Core Workflows:
-   https://admin-docs.zammad.org/en/latest/system/core-workflows.html
+   If you want to hide fields, consider :admin-docs:`Core Workflows </system/core-workflows.html>`
+   instead. For states and priorities use either API endpoints or rails console.
 
 List
 ====

api/organization.rst

@@ -313,7 +313,7 @@ Response:
       ],
       "secondary_member_ids": []
    }
-   
+
 Delete
 ======
 
@@ -327,10 +327,8 @@ Required permission: ``admin.organization``
    is not possible via API - this will be indicated by
    ``"error": "Can't delete, object has references."``. This is *not* a bug.
 
-   Consider using `Data Privacy`_ via UI for more control instead.
-
-.. _Data Privacy:
-   https://admin-docs.zammad.org/en/latest/system/data-privacy.html
+   Consider using :admin-docs:`Data Privacy </system/data-privacy.html>` via UI
+   for more control instead.
 
 ``DELETE``-Request sent: ``/api/v1/organizations/{id}``
 

api/user.rst

@@ -7,10 +7,8 @@ User
    ``ticket.agent`` permissions. Some attributes / information may not be
    available in specific situations.
 
-   Please see our `Permission Guide`_ to get better insights.
-
-.. _Permission Guide:
-   https://admin-docs.zammad.org/en/latest/manage/roles/index.html#reference-guide-permissions
+   Please see our :admin-docs:`Permission Guide </manage/roles/index.html#reference-guide-permissions>`
+   to get better insights.
 
 me - current user
 =================
@@ -1181,21 +1179,15 @@ Create
 ======
 
 Required permission: ``admin.user`` **or** ``ticket.agent``
-   
+
    .. note:: **🤓 This depends on permissions**
 
       Agents can't set user passwords, roles or group permission. Instead
-      Zammad will apply to `default sign up role`_.
+      Zammad will apply to :admin-docs:`default sign up role </manage/roles/index.html#role-details>`.
 
       Technically unauthenticated user creation is possible if you manage
       to provide the required CSRF token (out of scope of this documentation).
-      If you don't want that, consider `disabling user registration`_.
-
-.. _default sign up role:
-   https://admin-docs.zammad.org/en/latest/manage/roles/index.html#role-details
-
-.. _disabling user registration:
-   https://admin-docs.zammad.org/en/latest/settings/security/base.html
+      If you don't want that, consider :admin-docs:`disabling user registration </settings/security/base.html>`.
 
    .. tip:: **🧐 Creation payloads can be big**
 
@@ -1332,7 +1324,7 @@ Required permission: ``admin.user`` **or** ``ticket.agent``
    .. note:: **🤓 This depends on permissions**
 
       Agents can't set user passwords, roles or group permission. Instead
-      Zammad will apply to `default sign up role`_.
+      Zammad will apply to :admin-docs:`default sign up role </manage/roles/index.html#role-details>`.
 
 ``PUT``-Request sent: ``/api/v1/users/{id}``
 
@@ -1464,10 +1456,8 @@ Required permission: ``admin.user``
    via API - this will be indicated by
    ``"error": "Can't delete, object has references."``. This is *not* a bug.
 
-   Consider using `Data Privacy`_ via UI for more control instead.
-
-.. _Data Privacy:
-   https://admin-docs.zammad.org/en/latest/system/data-privacy.html
+   Consider using :admin-docs:`Data Privacy </system/data-privacy.html>` via UI
+   for more control instead.
 
 ``DELETE``-Request sent: ``/api/v1/users/{id}``
 

appendix/backup-and-restore/configuration.rst

@@ -67,11 +67,8 @@ After this you'll be ready to continue with either
    Zammad database together with the attachments you've stored within the file
    system.
 
-   Please refer `Storage Settings`_ to learn how to change the
-   storage location of your attachments.
-
-.. _Storage Settings:
-   https://admin-docs.zammad.org/en/latest/settings/system/storage.html
+   Please refer :admin-docs:`Storage Settings </settings/system/storage.html>`
+   to learn how to change the storage location of your attachments.
 
 ``DEBUG``
    Default: ``no`` (accepts: ``yes`` or ``no``)

appendix/backup-and-restore/migrate-hosts.rst

@@ -46,10 +46,7 @@ Step 2: Install Zammad on the destination host
 
 Step 3: Activate maintenance mode
    This ends agents and customers sessions.
-   `Learn more about the maintenance mode in Zammad`_.
-
-.. _Learn more about the maintenance mode in Zammad:
-   https://admin-docs.zammad.org/en/latest/system/maintenance.html
+   Learn more about :admin-docs:`the maintenance mode in Zammad </system/maintenance.html>`.
 
 Step 4: Disable your communication channels
    This is just a safety measurement. As our restore scripts starts Zammad
@@ -205,20 +202,15 @@ Step 11: Re-enable Channels and deactivate maintenance mode
    After verifying the functionality of your channels, allow your agents and
    customers back in by disabling the maintenance mode.
 
-   `Learn more about the maintenance mode in Zammad`_.
+   Learn more about :admin-docs:`the maintenance mode in Zammad </system/maintenance.html>`.
 
    .. hint:: *Migrated from Zammad SaaS or switching providers?*
 
-      Please make sure that your `notification`_ and `FQDN`_ configuration
-      is still correct. Other wise you may have unexpected issues like not
+      Please make sure that your :admin-docs:`notification </channels/email/accounts/email-notification.html>`
+      and :admin-docs:`FQDN </settings/system/base.html>` configuration is
+      still correct. Other wise you may have unexpected issues like not
       receiving notifications or non functional authentications (3rd party).
 
-.. _notification:
-   https://admin-docs.zammad.org/en/latest/channels/email/accounts/email-notification.html
-
-.. _FQDN:
-   https://admin-docs.zammad.org/en/latest/settings/system/base.html
-
 Step 12 (optional): Update Zammad to latest possible version
    In case the backup source was not on the latest possible version, please
    update your Zammad installation now.

appendix/backup-and-restore/troubleshooting.rst

@@ -79,11 +79,9 @@ Here's some classics you may encounter.
    This warning will be shown once before creating an empty directory to allow
    the backup process to continue successfully.
 
-   If you believe that this is an error, please see `Storage Settings`_.
+   If you believe that this is an error, please see
+   :admin-docs:`Storage Settings </settings/system/storage.html>`.
    In case the issue posts, please consult the `Zammad Community`_.
 
-.. _Storage Settings:
-   https://admin-docs.zammad.org/en/latest/settings/system/storage.html
-
 .. _Zammad Community:
    https://community.zammad.org/c/trouble-running-zammad-this-is-your-place/5

appendix/configure-env-vars.rst

@@ -40,8 +40,7 @@ General Options
 
 APP_RESTART_CMD
    The command Zammad will use to automatically restart the server
-   after `changes have been made in the Object Manager
-   <https://admin-docs.zammad.org/en/latest/system/objects.html>`_.
+   after :admin-docs:`changes have been made in the Object Manager </system/objects.html>`.
    (*E.g.,* ``"systemctl restart zammad"``)
 
    If this is undefined, you will have to restart manually

appendix/privacy.rst

@@ -12,12 +12,12 @@ Tickets and users
    By default, Zammad never automatically deletes tickets or users.
 
    To enable **automatic** deletion of tickets after a given interval,
-   `use the scheduler <https://admin-docs.zammad.org/en/latest/manage-scheduler.html>`_.
+   :admin-docs:`use the scheduler </manage/scheduler.html>`.
 
    To **manually** delete users and all their associated tickets
    (*e.g.* in compliance with a “Right to Forget” request under the GDPR),
    you can use the
-   `data privacy functions <https://admin-docs.zammad.org/en/latest/system/data-privacy.html>`_
+   :admin-docs:`data privacy functions </system/data-privacy.html>`
    in the admin panel or
    :doc:`use the console </admin/console/dangerzone-for-experts>`.
 

appendix/reporting-tools-thirdparty.rst

@@ -13,10 +13,9 @@ This guide will discuss how to set up third party reporting tools with Zammad.
 .. IGNORE THE NEXT BLOCK - This functionality is not yet available.
    .. note:: **💰 Availability**
 
-      The following information require either a self-hosted installation or 
-      a hosted instance with **PLUS** package. If you're a Hosted user, please 
-      also check `the Elasticsearch integration 
-      <https://admin-docs.zammad.org/en/latest/system/integrations/hosted/elasticsearch.html>`_ 
+      The following information require either a self-hosted installation or
+      a hosted instance with **PLUS** package. If you're a Hosted user, please
+      also check :admin-docs:`the Elasticsearch integration </system/integrations/elasticsearch.html>`
       page for information on how to hook your tool to the index.
 
 Getting Started

appendix/single-sign-on.rst

@@ -28,9 +28,8 @@ so that anyone with an account on your local intranet will
 
 .. note:: If you *don’t* have this IT infrastructure
    but still want one-click login,
-   see `Third-Party Authentication`_ for alternatives.
-
-   .. _Third-Party Authentication: https://admin-docs.zammad.org/en/latest/settings/security.html#third-party-applications
+   see :admin-docs:`Third-Party Authentication </settings/security.html#third-party-applications>`
+   for alternatives.
 
 How does it work?
 ^^^^^^^^^^^^^^^^^
@@ -92,12 +91,10 @@ You will need:
 
 * some familiarity with system administration (*e.g.,* Apache configuration)
 
-For best results, set up `LDAP integration`_
+For best results, set up :admin-docs:`LDAP integration </system/integrations/ldap/index.html>`
 to make sure your Active Directory and Zammad user accounts
 are always in sync.
 
-.. _LDAP integration: https://admin-docs.zammad.org/en/latest/system/integrations/ldap.html
-
 .. _sso-register-spn:
 
 Step 1: Configure Active Directory