QubesOS · parulin · Sep 16, 2025 · Sep 16, 2025
diff --git a/developer/general/developing-gui-applications.rst b/developer/general/developing-gui-applications.rst
@@ -63,7 +63,7 @@ If error should be thrown, you need to provide the error code and name, for exam
           b'2\x00QubesNoSuchPropertyError\x00\x00No such property\x00'
 
 
-For details of particular calls, you can use `Extending the mock Qubes object <#extending-the-mock-qubes-object>`__.
+For details of particular calls, you can use :ref:`developer/general/developing-gui-applications:extending the mock qubes object`.
 
 Available mocks
 ---------------

diff --git a/developer/general/how-to-edit-the-website.rst b/developer/general/how-to-edit-the-website.rst
@@ -24,7 +24,7 @@ hosted on `GitHub <https://github.com/>`__.
 
 A few notes to consider:
 
-- Since Qubes is a security-oriented project, every change will be `reviewed <#security>`__ before it’s accepted. This allows us to maintain quality control and protect our users.
+- Since Qubes is a security-oriented project, every change will be :ref:`reviewed <developer/general/how-to-edit-the-website:security>` before it’s accepted. This allows us to maintain quality control and protect our users.
 - To give your contribution a better chance of being accepted, please follow our :doc:`website style guide </developer/general/website-style-guide>`.
 - We don’t want you to spend time and effort on a contribution that we can’t accept. If your contribution would take a lot of time, please :doc:`file an issue </introduction/issue-tracking>` for it first so that we can make sure we’re on the same page before significant works begins.
 - Finally, if you’ve written something that doesn’t belong in `qubesos.github.io <https://github.com/QubesOS/qubesos.github.io>`__ but would be beneficial to the Qubes community, please consider adding it to the :doc:`documentation </developer/general/how-to-edit-the-rst-documentation>` or the :ref:`external documentation <developer/general/rst-documentation-style-guide:core vs. external documentation>`.
@@ -212,7 +212,7 @@ Once a pull request passes review, the reviewer should add a signed comment stat
 Questions, problems, and improvements
 -------------------------------------
 
-If you have a question about something you read in the website or about how to edit the it, please post it on the `forum <https://forum.qubes-os.org/>`__ or send it to the appropriate :doc:`mailing list </introduction/support>`. If you see that something in the website should be fixed or improved, please `contribute <#how-to-submit-a-pull-request>`__ the change yourself. To report an issue with the wesbite, please follow our standard :doc:`issue reporting guidelines </introduction/issue-tracking>`. (If you report an issue with the website, you will likely be asked to submit a pull request for it, unless there is a clear indication in your report that you are not willing or able to do so.)
+If you have a question about something you read in the website or about how to edit the it, please post it on the `forum <https://forum.qubes-os.org/>`__ or send it to the appropriate :doc:`mailing list </introduction/support>`. If you see that something in the website should be fixed or improved, please :ref:`contribute <developer/general/how-to-edit-the-website:how to submit a pull request>` the change yourself. To report an issue with the wesbite, please follow our standard :doc:`issue reporting guidelines </introduction/issue-tracking>`. (If you report an issue with the website, you will likely be asked to submit a pull request for it, unless there is a clear indication in your report that you are not willing or able to do so.)
 
 .. |news-section| image:: /attachment/doc/website_news_section.png
    :alt: Depicts the News section of the Qubes OS website

diff --git a/developer/general/package-contributions.rst b/developer/general/package-contributions.rst
@@ -35,15 +35,15 @@ Contribution Procedure
 
 Before you start putting serious work into a package, we recommend that you discuss your idea with the Qubes developers and the broader community on the :ref:`qubes-devel mailing list <introduction/support:qubes-devel>`. Once you have a package that’s ready to become part of Qubes OS, please follow this procedure:
 
-1. Ensure that your package satisfies the `Inclusion Criteria <#inclusion-criteria>`__.
+1. Ensure that your package satisfies the :ref:`developer/general/package-contributions:inclusion criteria`.
 
 2. If your code isn’t already on GitHub, create a GitHub repo that contains your code. You can have a look to an example package called `qubes-skeleton <https://github.com/QubesOS-contrib/qubes-skeleton>`__.
 
 3. If you haven’t already, :doc:`sign your code </developer/code/code-signing>`.
 
 4. Create an issue in `qubes-issues <https://github.com/QubesOS/qubes-issues/issues/>`__ with the title ``[Contribution] your-package-name``. Include a link to your repo, a brief description of your package, and a brief explanation of why you think it should be included in Qubes. Please note that the Qubes core developers are very busy. If they are under heavy load when you submit your contribution, it may be a very long time before they have time to review your package. If this happens, please do not be discouraged. If you think they may have forgotten about your pending contribution, you may “bump” your request by commenting on your issue, but please do this *very* sparingly (i.e., no more than once a month). We appreciate your understanding!
 
-5. You may be asked followup questions. If we decide to accept your contribution, you will be invited to join the `QubesOS-contrib <https://github.com/QubesOS-contrib>`__ organization on GitHub as public recognition of your contribution (but without push access; see `Review Procedure <#review-procedure>`__), and `QubesOS-contrib <https://github.com/QubesOS-contrib>`__ will fork your repo. If we decide not to accept your contribution, we will state the reason and close the issue.
+5. You may be asked followup questions. If we decide to accept your contribution, you will be invited to join the `QubesOS-contrib <https://github.com/QubesOS-contrib>`__ organization on GitHub as public recognition of your contribution (but without push access; see :ref:`developer/general/package-contributions:review procedure`), and `QubesOS-contrib <https://github.com/QubesOS-contrib>`__ will fork your repo. If we decide not to accept your contribution, we will state the reason and close the issue.
 
 
 
@@ -59,7 +59,7 @@ Review Procedure
 ----------------
 
 
-This review procedure covers both original package contributions (see `Contribution Procedure <#contribution-procedure>`__) and all subsequent updates to those packages, including updates from the original package contributor (see `Update Procedure <#update-procedure>`__). All changes will be reviewed by a Qubes Core Reviewer (QCR) and the `Package Maintainer <#package-maintainers>`__ (PM). In all cases, the QCR will be a core Qubes developer. In some cases, the QCR and the PM will be the same person. For example, if someone contributes a package, then disappears, and no suitable replacement has been found, then it is likely that a core Qubes developer will play both the QCR and PM roles for that package, at least until another suitable candidate volunteers to become the PM for that package.
+This review procedure covers both original package contributions (see :ref:`developer/general/package-contributions:contribution procedure`) and all subsequent updates to those packages, including updates from the original package contributor (see :ref:`developer/general/package-contributions:update procedure`). All changes will be reviewed by a Qubes Core Reviewer (QCR) and the :ref:`Package Maintainer <developer/general/package-contributions:package maintainers>` (PM). In all cases, the QCR will be a core Qubes developer. In some cases, the QCR and the PM will be the same person. For example, if someone contributes a package, then disappears, and no suitable replacement has been found, then it is likely that a core Qubes developer will play both the QCR and PM roles for that package, at least until another suitable candidate volunteers to become the PM for that package.
 
 The review procedure is as follows:
 
@@ -97,7 +97,7 @@ Package Maintainers
 
 If you contribute a package, we assume that you will be the maintainer of that package, unless you tell us otherwise. As the maintainer of the package, it is your privilege and responsibility to:
 
-- `Review <#review-procedure>`__ each pull request made against the package.
+- :ref:`Review <developer/general/package-contributions:review procedure>` each pull request made against the package.
 
 - Decide when the package has reached a new version, and notify the Qubes core developers when this occurs.
 

diff --git a/developer/general/website-style-guide.rst b/developer/general/website-style-guide.rst
@@ -109,7 +109,7 @@ HTML and CSS
 ^^^^^^^^^^^^
 
 
-Do not write HTML inside Markdown documents (except in rare, unavoidable cases, such as `alerts <#alerts>`__). In particular, never include HTML or CSS for styling, formatting, or white space control. That belongs in the (S)CSS files instead.
+Do not write HTML inside Markdown documents (except in rare, unavoidable cases, such as :ref:`developer/general/website-style-guide:alerts`). In particular, never include HTML or CSS for styling, formatting, or white space control. That belongs in the (S)CSS files instead.
 
 Headings
 ^^^^^^^^
@@ -161,7 +161,7 @@ There are two problems with this:
 
 
 
-Instead, an example of an appropriate way to stylistically distinguish a portion of text is by using `alerts <#alerts>`__. Consider also that extra styling and visual distinction may not even be necessary. In most cases, traditional writing methods are perfectly sufficient, e.g.,:
+Instead, an example of an appropriate way to stylistically distinguish a portion of text is by using :ref:`developer/general/website-style-guide:alerts`. Consider also that extra styling and visual distinction may not even be necessary. In most cases, traditional writing methods are perfectly sufficient, e.g.,:
 
 .. code:: markdown
 

diff --git a/developer/services/qrexec.rst b/developer/services/qrexec.rst
@@ -212,7 +212,7 @@ When calling a service that takes an argument, just add the argument to the serv
 
 The script will receive ``ARGUMENT`` as its argument. The argument will also become available as the ``QREXEC_SERVICE_ARGUMENT`` environment variable. This means it is possible to install a different script for a particular service argument.
 
-See `below <#rpc-service-with-argument-file-reader>`__ for an example of an RPC service using an argument.
+See :ref:`developer/services/qrexec:rpc service with argument (file reader)` for an example of an RPC service using an argument.
 
 Qubes RPC examples
 ------------------
@@ -278,7 +278,7 @@ RPC service with argument (file reader)
 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
 
 
-Here we create an RPC call that reads a specific file from a predefined directory on the target. This example uses an `argument <#service-policies-with-arguments>`__ to the policy. In this example a simplified workflow will be used. The service code is placed directly in the service definition file on the target VM. No separate client script will be needed.
+Here we create an RPC call that reads a specific file from a predefined directory on the target. This example uses an :ref:`argument <developer/services/qrexec:service policies with arguments>` to the policy. In this example a simplified workflow will be used. The service code is placed directly in the service definition file on the target VM. No separate client script will be needed.
 
 First, on your target VM, create two files in the home directory: ``testfile1`` and ``testfile2``. Have them contain two different “Hello world!” lines.
 

diff --git a/developer/services/qrexec2.rst b/developer/services/qrexec2.rst
@@ -102,7 +102,7 @@ By default, stderr of client and server is logged to respective ``/var/log/qubes
 
 Be very careful when coding and adding a new RPC service! Any vulnerability in a RPC server can be fatal to security of the target VM!
 
-If requesting VM-VM (and VM-Dom0) services execution *without cmdline helper*, connect directly to ``/var/run/qubes/qrexec-agent-fdpass`` socket as described `below <#all-the-pieces-together-at-work>`__.
+If requesting VM-VM (and VM-Dom0) services execution *without cmdline helper*, connect directly to ``/var/run/qubes/qrexec-agent-fdpass`` socket as described :ref:`below <developer/services/qrexec2:all the pieces together at work>`.
 
 Revoking "Yes to All" authorization
 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^