fixed reference errors, minor enhancements to the docs, fix pyproject.toml, alt text to images

.gitignore

@@ -1,2 +1,4 @@
 _build
 **/__pycache__/*
+uv.lock
+poetry.lock

developer/general/how-to-edit-the-rst-documentation.rst

@@ -5,10 +5,11 @@ How to edit the documentation
 The Qubes OS documentation is stored as `reStructuredText (rST) <https://docutils.sourceforge.io/rst.html>`__ files in
 the `qubes-doc <https://github.com/QubesOS/qubes-doc>`__ repository.
 We use `Sphinx <https://www.sphinx-doc.org/>`__ for building and
-`Read The Docs <https://readsthedocs.com/>`__ for hosting.
+`Read The Docs (RTD) <https://readsthedocs.com/>`__ for hosting.
+RTD is a `continuous‑documentation deployment platform <https://docs.readthedocs.com/platform/stable/continuous-deployment.html>`__ that automatically detects changes in the qubes-doc GittHub repository and builds the latest version of the docs.
 
 .. figure:: /attachment/doc/rst-rtd-workflow.png
-    :alt: Qubes OS Documentation Workflow - TODO description
+    :alt: Qubes OS Documentation Workflow - once new documentation is written or changed, it is built and verified with Sphinx, pushed on GitHub/GitLab and hosted on RTD
     :scale: 15 %
     :align: center
 
@@ -21,8 +22,7 @@ be downloaded from `doc.qubes-os.org <https://doc.qubes-os.org/en/latest/>`__:
 |epub-pdf|
 
 ..
-  TODO screenshot with main branch instead of rst
-  TODO add alt description overall with the images
+  TODO screenshots with main branch instead of rst when rst merged in main 
   TODO add draft pull request screenshot
 
 The documentation is a volunteer community effort. People like you are
@@ -64,12 +64,13 @@ Ok, let’s begin. Every documentation page has a “Edit on GitHub” link.
 
 When you click on it, you’ll be taken to the source file — a reStructuredText (``.rst``) file — on GitHub.
 
-|github-edit|
-
 On this page, there will be a
 button to edit the file (if you are already logged in in).
 
-TODO screenshot
+..
+  TODO screenshot when rst merged in main
+
+|github-edit|
 
 If you are not logged in you can click on :guilabel:`Sign In`
 and you’ll be prompted to sign in with your GitHub username and password.
@@ -105,7 +106,7 @@ if you want to locally verify that everything looks correct before submitting an
 
 
 Once you’re finished, describe your changes at the bottom and click
-:guilabel:`Propose file change`.
+:guilabel:`Commit changes`.
 
 |commit|
 
@@ -115,8 +116,6 @@ stage, those changes are still in your own copy of the documentation
 the :guilabel:`Create pull request` button.
 
 
-|draft-pull-request-confirm|
-
 You will be able to adjust the pull request message and title there. In
 most cases, the defaults are ok, so you can just confirm by pressing the
 :guilabel:`Create pull request` button again. However, if you’re not ready for
@@ -140,7 +139,8 @@ can’t.
 Viewing your pull request on RTD
 --------------------------------
 
-To view your pull request on RTD you can go to Qubes OS builds on `RTD <https://app.readthedocs.org/projects/qubes-doc/builds/>`__:
+Every time you push a commit to your pull request, a build on RTD will be triggered.
+To view your PR you can go to Qubes OS builds on `RTD <https://app.readthedocs.org/projects/qubes-doc/builds/>`__:
 
 |pull-request-builds|
 
@@ -184,7 +184,10 @@ TL;DR: How to edit the documentation index
 For a more comprehensive guide to the rST syntax and pitfalls please refer to the :doc:`reStrucutredText Style Guide </developer/general/rst-documentation-style-guide/>`.
 
 The source file for the :doc:`documentation index (a.k.a. table of contents) </index>` is
-`index.rst <https://github.com/QubesOS/qubes-doc/blob/rst/index.rst>`__ (TODO: main).
+`index.rst <https://github.com/QubesOS/qubes-doc/blob/rst/index.rst>`__.
+
+..
+  TODO: point to index, conf.py etc on main not on rst when rst merged in main
 
 
 :file:`index.rst` contains information about the hierarchy between the files in the documentation and/or
@@ -231,7 +234,7 @@ Then, add your image(s) in a the :file:`attachment/doc` folder in the `qubes-doc
 repository using the same path and filename.
 This is the only permitted way to include images. Do not link to images on other websites.
 
-.. _cross_refrencing:
+.. _cross_referencing:
 
 TL;DR: Cross-referencing
 ========================
@@ -267,7 +270,7 @@ which will point to :ref:`this section <user/troubleshooting/vm-troubleshooting:
 which will refer to :ref:`this section <introduction/faq:what does it mean to "distrust the infrastructure"?>`.
 
 
-TODO: label of sections and referencing them
+For further options and use cases please refer to `Cross-references <https://www.sphinx-doc.org/en/master/usage/referencing.html>`__.
 
 
 .. _build_locally:
@@ -280,7 +283,7 @@ In order to build the Qubes OS rST documentation locally clone the `qubes-doc <h
 (or your forked one if you want to submit a pull request).
 
 
-It is recommended to use a virtual environment, f.ex. venv or poetry.
+It is recommended to use a virtual environment, f.ex. venv or uv poetry.
 In the following section there is a sample setup to prepare local environments
 for building Qubes OS rST documentation.
 
@@ -368,7 +371,7 @@ Using poetry
 
 
 1. `Install poetry <https://python-poetry.org/docs/#installation>`__ and git and clone the repository.
-A `pyproject.toml` file is provided.
+A :file:`pyproject.toml` file is provided.
 
   .. code-block:: console
 
@@ -456,7 +459,7 @@ You can find it `here <https://github.com/QubesOS/qubes-doc/blob/rst/conf.py>`__
 Extensions
 ----------
 
-We use several Sphinx `extensions<https://www.sphinx-doc.org/en/master/usage/extensions/index.html>`__
+We use several Sphinx `extensions <https://www.sphinx-doc.org/en/master/usage/extensions/index.html>`__
 as defined in :file:`conf.py`, as well a simple custom one to embed YouTube videos,
 which can be found `here <https://github.com/QubesOS/qubes-doc/tree/rst/_ext>`__.
 
@@ -504,16 +507,26 @@ you are not willing or able to do so.)
 
 
 .. |page-source-button| image:: /attachment/doc/doc-pr_01_page-source-button-rtd.png
+   :alt: Highlights the Edit Source Button to GitHub sources on doc.qubes-os.org
 .. |github-edit| image:: /attachment/doc/doc-pr_02_github-edit-rst.png
+   :alt: Highlights the Sign-In on GitHub
 .. |github-sign-in| image:: /attachment/doc/doc-pr_03_sign-in-rst.png
+   :alt: GitHub Login
 .. |fork1| image:: /attachment/doc/doc-pr_04_fork-rst1.png
+   :alt: Highlights the Fork Button on GitHub for the qubes-doc repository
 .. |fork2| image:: /attachment/doc/doc-pr_04_fork-rst2.png
+   :alt: Highlights the Create Fork Button on GitHub when forking the qubes-doc repository
 .. |fork3| image:: /attachment/doc/doc-pr_04_fork-rst3.png
+   :alt: Forked qubes-doc repository on GitHub
 .. |edit| image:: /attachment/doc/doc-pr_05_edit-rst.png
+   :alt: Highlights the edit options for an rst file in the GitHub forked qubes-doc repository
 .. |commit| image:: /attachment/doc/doc-pr_06_commit-msg-rst.png
+   :alt: Highlights the commit changes button on GitHub
 .. |pull-request-confirm| image:: /attachment/doc/doc-pr_09_create-pr-rst.png
-.. |draft-pull-request-confirm| image:: /attachment/doc/doc-pr_09_create-dpr-rst.png
+   :alt: Highlights the create pull request button on GitHub when creating a pull request
 .. |pull-request-builds| image:: /attachment/doc/doc-pr_10_view-pr-rtd.png
+   :alt: Highlights the pull request <number> and its build in the build list on RTD
 .. |pull-request-build| image:: /attachment/doc/doc-pr_11_view-pr-rtd.png
-.. |done| image:: /attachment/doc/doc-pr_09_done.png
+   :alt: Highlights the View Docs button in a specific build for a pull request <number> on RTD
 .. |epub-pdf| image:: /attachment/doc/rst-rtd-epub-pdf.png
+   :alt: Highlights from where one can download a ePUB or PDF of hte Qubes OS documentation deployed on RTD

developer/general/how-to-edit-the-website.rst

@@ -216,4 +216,6 @@ 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.)
 
 .. |news-section| image:: /attachment/doc/website_news_section.png
+   :alt: Depicts the News section of the Qubes OS website
 .. |hcl-section| image:: /attachment/doc/website_hcl.png
+   :alt: Depicts the Hardware Compatibility List table on the Qubes OS website

developer/general/rst-documentation-style-guide.rst

@@ -308,7 +308,7 @@ use `:ref:` for specific sections
    :ref:`qubes <user/reference/glossary:qube>`
 
 
-For further information please :ref:`see <developer/general/how-to-edit-the-rst-documentation:cross-referencing>`.
+For further information please :ref:`cross_referencing`.
 
 
 Hyperlink syntax
@@ -331,7 +331,7 @@ Do *not* use reference-style links like
 
 This facilitates the localization process.
 
-Take a look also :ref:`here <developer/general/how-to-edit-the-rst-documentation:cross-referencing>`.
+Take a look also :ref:`cross_referencing`.
 
 
 Relative vs. absolute links
@@ -570,7 +570,7 @@ Core vs. external documentation
 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
 
 
-Core documentation resides in the `Qubes OS Project’s official repositories <https://github.com/QubesOS/>`__, mainly in `qubes-doc <https://github.com/QubesOS/qubes-doc>`__. External documentation can be anywhere else (such as forums, community websites, and blogs), but there is an especially large collection in the `Qubes Forum <https://forum.qubes-os.org/docs>`__. External documentation should not be submitted to `qubes-doc <https://github.com/QubesOS/qubes-doc>`__. If you’ve written a piece of documentation that is not appropriate for `qubes-doc <https://github.com/QubesOS/qubes-doc>`__, we encourage you to submit it to the `Qubes Forum <https://forum.qubes-os.org/docs>`__ instead. However, *linking* to external documentation from `qubes-doc <https://github.com/QubesOS/qubes-doc>`__ is perfectly fine. Indeed, the maintainers of the `Qubes Forum <https://forum.qubes-os.org/>`__ should regularly submit PRs against the documentation index (see :ref:`How to edit the documentation index <developer/general/how-to-edit-the-rst-documentation:how to edit the documentation index>`) to add and update Qubes Forum links in the :ref:`“External documentation” <index:external documentation>` section of the documentation table of contents.
+Core documentation resides in the `Qubes OS Project’s official repositories <https://github.com/QubesOS/>`__, mainly in `qubes-doc <https://github.com/QubesOS/qubes-doc>`__. External documentation can be anywhere else (such as forums, community websites, and blogs), but there is an especially large collection in the `Qubes Forum <https://forum.qubes-os.org/docs>`__. External documentation should not be submitted to `qubes-doc <https://github.com/QubesOS/qubes-doc>`__. If you’ve written a piece of documentation that is not appropriate for `qubes-doc <https://github.com/QubesOS/qubes-doc>`__, we encourage you to submit it to the `Qubes Forum <https://forum.qubes-os.org/docs>`__ instead. However, *linking* to external documentation from `qubes-doc <https://github.com/QubesOS/qubes-doc>`__ is perfectly fine. Indeed, the maintainers of the `Qubes Forum <https://forum.qubes-os.org/>`__ should regularly submit PRs against the documentation index (see :ref:`edit_doc_index`) to add and update Qubes Forum links in the :ref:`“External documentation” <index:external documentation>` section of the documentation table of contents.
 
 The main difference between **core** (or **official**) and **external** (or **community** or **unofficial**) documentation is whether it documents software that is officially written and maintained by the Qubes OS Project. The purpose of this distinction is to keep the core docs maintainable and high-quality by limiting them to the software output by the Qubes OS Project. In other words, we take responsibility for documenting all of the software we put out into the world, but it doesn’t make sense for us to take on the responsibility of documenting or maintaining documentation for anything else. For example, Qubes OS may use a popular Linux distribution for an official :doc:`TemplateVM </user/templates/templates>`. However, it would not make sense for a comparatively small project like ours, with modest funding and a lean workforce, to attempt to document software belonging to a large, richly-funded project with an army of paid and volunteer contributors, especially when they probably already have documentation of their own. This is particularly true when it comes to Linux in general. Although many users who are new to Qubes are also new to Linux, it makes absolutely no sense for our comparatively tiny project to try to document Linux in general when there is already a plethora of documentation out there.
 
@@ -751,7 +751,7 @@ Internal
         :doc:`Link Text </path/to/file>`
 
 
-For example on cross referencing please see :ref:`cross-referencing <developer/general/how-to-edit-the-rst-documentation:cross-referencing>`.
+For example on cross referencing please see :ref:`cross_referencing`.
 
 Text Decoration
 ^^^^^^^^^^^^^^^
@@ -865,4 +865,3 @@ Markdown does not have built-in support for alerts and warnings.
 
         .. danger::
            This is a danger message.
-

developer/general/website-style-guide.rst

@@ -397,3 +397,4 @@ Git conventions
 Please follow our :ref:`Git commit message guidelines <developer/code/coding-style:commit message guidelines>`.
 
 .. |alerts| image:: /attachment/doc/website_alerts.png
+   :alt: Depicts different alerts and messages: note, warning, danger and how they are rendered on the website

introduction/getting-started.rst

@@ -192,13 +192,6 @@ Documentation
 Browse our extensive library of :doc:`documentation </index>` for users and developers of Qubes OS. You can even :doc:`help us improve it </developer/general/how-to-edit-the-rst-documentation>`!
 
 .. |snapshot_41.png| image:: /attachment/doc/r4.1-snapshot_40.png
-   
-
 .. |r4.0-taskbar.png| image:: /attachment/doc/r4.0-taskbar.png
-   
-
 .. |r4.1-widgets.png| image:: /attachment/doc/r4.1-widgets.png
-   
-
 .. |r4.1-qubes-manager.png| image:: /attachment/doc/r4.1-qubes-manager.png
-   

introduction/intro.rst

@@ -15,7 +15,7 @@ single-user desktop computing. Qubes OS `leverages Xen-based virtualization <htt
 
 
 These qubes, which are implemented as :term:`virtual machines (VMs) <vm>`, have specific:
-               
+
 - **Purposes:** with a predefined set of one or many isolated
   applications, for personal or professional projects, to manage the
   :doc:`network stack </developer/system/networking>`, :doc:`the firewall </user/security-in-qubes/firewall>`, or to fulfill other
@@ -25,7 +25,7 @@ These qubes, which are implemented as :term:`virtual machines (VMs) <vm>`, have
   :doc:`stripped-down </introduction/getting-started/>` virtual machines based on popular operating systems,
   such as :doc:`Fedora </user/templates/fedora/fedora>`, :doc:`Debian </user/templates/debian/debian>`, and
   `Windows <https://github.com/Qubes-Community/Contents/blob/master/docs/os/windows/windows.md>`__.
-               
+
 - **Levels of trust:** from complete to non-existent. All windows are displayed in a unified desktop environment with
   :doc:`unforgeable colored window borders </introduction/getting-started>` so that different security levels are easily identifiable.
 
@@ -52,7 +52,7 @@ Features
 - **Multiple operating systems** Use multiple operating systems at the same time, including
   :doc:`Fedora </user/templates/fedora/fedora>`, :doc:`Debian </user/templates/debian/debian/>`, and
   `Windows <https://github.com/Qubes-Community/Contents/blob/master/docs/os/windows/windows.md>`__
-         
+
 - **Disposables** Create :doc:`disposables </user/how-to-guides/how-to-use-disposables>` on the fly that self-destruct when shut down.
 
 - **Whonix integration** Run `Tor <https://www.torproject.org/>`__ securely system-wide using `Whonix with Qubes <https://www.whonix.org/wiki/Qubes>`__.
@@ -142,7 +142,7 @@ plug in devices, and install software free from worry. It's a place where
 **you** have control over your software, not the other way around.
 (See some :doc:`examples of how different types of users organize their qubes </user/how-to-guides/how-to-organize-your-qubes>`.)
 
-Qubes is also powerful. Organizations like the `Freedom of the Press Foundation <https://securedrop.org/news/piloting-securedrop-workstation-qubes-os>`__, 
+Qubes is also powerful. Organizations like the `Freedom of the Press Foundation <https://securedrop.org/news/piloting-securedrop-workstation-qubes-os>`__,
 `Mullvad <https://twitter.com/mullvadnet/status/631010362083643392>`__,
 and `Let's Encrypt <https://twitter.com/letsencrypt/status/1239934557710737410>`__
 rely on Qubes as they build and maintain critical privacy and
@@ -193,6 +193,6 @@ presentation.
 
 - If you’re a current or potential Qubes user, you may want to check out the :doc:`documentation </index>` and the :ref:`user FAQ <introduction/faq:users>`.
 - If you’re a developer, there’s dedicated :ref:`index:Developer Documentation` and a :ref:`developer FAQ <introduction/faq:developers>` just for you.
-- Ready to give Qubes a try? Head on over to the `downloads page <https://www.qubes-os.org/downloads/>`__, and read the :ref:`Installation guide`.
+- Ready to give Qubes a try? Head on over to the `downloads page <https://www.qubes-os.org/downloads/>`__, and read the :doc:`Installation guide </user/downloading-installing-upgrading/installation-guide>`.
 - Need help, or just want to join the conversation? Learn more about :doc:`help, support, the mailing lists, and the forum </introduction/support>`.
 

introduction/screenshots.rst

@@ -130,61 +130,22 @@ And some more screenshots:
 |r2b3-windows-seamless-2.png|
 
 .. |r4.0-xfce-desktop.png| image:: /attachment/doc/r4.0-xfce-desktop.png
-   
-
 .. |r4.0-xfce-start-menu.png| image:: /attachment/doc/r4.0-xfce-start-menu.png
-   
-
 .. |r4.0-xfce-three-domains-at-work.png| image:: /attachment/doc/r4.0-xfce-three-domains-at-work.png
-   
-
 .. |r2b3-windows-seamless-1.png| image:: /attachment/doc/r2b3-windows-seamless-1.png
-   
-
 .. |r2b3-windows-seamless-filecopy.png| image:: /attachment/doc/r2b3-windows-seamless-filecopy.png
-   
-
 .. |r4.0-xfce-programmers-desktop.png| image:: /attachment/doc/r4.0-xfce-programmers-desktop.png
-   
-
 .. |r4.0-password-prompt.png| image:: /attachment/doc/r4.0-password-prompt.png
-   
-
 .. |r4.0-xfce-tray-icons.png| image:: /attachment/doc/r4.0-xfce-tray-icons.png
-   
-
 .. |r4.0-manager-and-sysnet-network-prompt.png| image:: /attachment/doc/r4.0-manager-and-sysnet-network-prompt.png
-   
-
 .. |r4.0-software-update.png| image:: /attachment/doc/r4.0-software-update.png
-   
-
 .. |r4.0-copy-paste.png| image:: /attachment/doc/r4.0-copy-paste.png
-   
-
 .. |“r4.0-copy-to-other-appvm-1.png| image:: /attachment/doc/r4.0-copy-to-other-appvm-1.png
-   
-
 .. |r4.0-copy-to-other-appvm-3.png| image:: /attachment/doc/r4.0-copy-to-other-appvm-2.png
-   
-
 .. |r4.0-open-in-dispvm-1.png| image:: /attachment/doc/r4.0-open-in-dispvm-1.png
-   
-
 .. |r4.0-open-in-dispvm-2.png| image:: /attachment/doc/r4.0-open-in-dispvm-2.png
-   
-
 .. |r4.0-convert-to-trusted-pdf-1.png| image:: /attachment/doc/r4.0-convert-to-trusted-pdf-1.png
-   
-
 .. |r4.1-converting-pdf.png| image:: /attachment/doc/r4.1-converting-pdf.png
-   
-
 .. |r4.0-manager-firewall.png| image:: /attachment/doc/r4.0-manager-firewall.png
-   
-
 .. |r4.0-xfce-red-and-green-terminals.png| image:: /attachment/doc/r4.0-xfce-red-and-green-terminals.png
-   
-
 .. |r2b3-windows-seamless-2.png| image:: /attachment/doc/r2b3-windows-seamless-2.png
-   

pyproject.toml

@@ -11,6 +11,10 @@ dependencies = ["sphinx (>=8.2.3,<9.0.0)"]
 requires = ["hatchling"]
 build-backend = "hatchling.build"
 
+
+[tool.poetry]
+package-mode = false
+
 [tool.uv]
 package = false
 
@@ -20,6 +24,8 @@ dev = [
     "sphinx-autobuild>=2024.10.3,<2025",
     "sphinx-lint>=1.0.0,<2",
     "sphinx-reredirects>=1.0.0,<2",
+    "sphinxext-opengraph==0.12.0",
+    "sphinxnotes-any==2.5",
     "sphinxnotes-strike>=1.2.1,<2",
     "sphinx-rtd-theme>=3.0.2,<4",
 ]

user/hardware/certified-hardware/certified-hardware.rst

@@ -6,7 +6,7 @@ Certified hardware
 The Qubes OS Project aims to partner with a select few computer vendors to ensure that Qubes users have reliable hardware purchasing options. We aim for these vendors to be as diverse as possible in terms of geography, cost, and availability.
 
 .. DANGER::
-      
+
       **Warning:** The Qubes OS Project certifies only that a particular hardware *configuration* is *supported* by Qubes OS and is available to purchase with Qubes OS preinstalled. We take no responsibility for any vendor’s manufacturing, shipping, payment, or other practices; nor can we control whether physical hardware is modified (whether maliciously or otherwise) *en route* to the user.
 
 You may also be interested in the `community-recommended hardware <https://forum.qubes-os.org/t/5560>`__ list and the `hardware compatibility list (HCL) <https://www.qubes-os.org/hcl/>`__.
@@ -19,8 +19,8 @@ Qubes-certified computers are certified for a :doc:`major release </developer/re
 
 The current Qubes-certified models are listed below in reverse chronological order of certification.
 
-.. list-table:: 
-   :widths: 43 43 43 
+.. list-table::
+   :widths: 43 43 43
    :align: center
    :header-rows: 1
 
@@ -28,22 +28,22 @@ The current Qubes-certified models are listed below in reverse chronological ord
      - Model
      - Certification details
    * - `NovaCustom <https://novacustom.com/>`__
-     - `V54 Series <https://novacustom.com/product/v54-series/>`__ 
+     - `V54 Series <https://novacustom.com/product/v54-series/>`__
      - :doc:`Certification details </user/hardware/certified-hardware/novacustom-v54-series/>`
    * - `Nitrokey <https://www.nitrokey.com/>`__
-     - `NitroPad V56 <https://shop.nitrokey.com/shop/nitropad-v56-684>`__ 
+     - `NitroPad V56 <https://shop.nitrokey.com/shop/nitropad-v56-684>`__
      - :doc:`Certification details </user/hardware/certified-hardware/nitropad-v56/>`
    * - `NovaCustom <https://novacustom.com/>`__
-     - `V56 Series <https://novacustom.com/product/v56-series/>`__ 
+     - `V56 Series <https://novacustom.com/product/v56-series/>`__
      - :doc:`Certification details </user/hardware/certified-hardware/novacustom-v56-series/>`
    * - `Nitrokey <https://www.nitrokey.com/>`__
-     - `NitroPC Pro 2 <https://shop.nitrokey.com/shop/nitropc-pro-2-523>`__ 
+     - `NitroPC Pro 2 <https://shop.nitrokey.com/shop/nitropc-pro-2-523>`__
      - :doc:`Certification details </user/hardware/certified-hardware/nitropc-pro-2/>`
    * - `Star Labs <https://starlabs.systems/>`__
-     - `StarBook <https://starlabs.systems/pages/starbook>`__ 
+     - `StarBook <https://starlabs.systems/pages/starbook>`__
      - :doc:`Certification details </user/hardware/certified-hardware/starlabs-starbook/>`
    * - `Nitrokey <https://www.nitrokey.com/>`__
-     - `NitroPC Pro <https://web.archive.org/web/20231027112856/https://shop.nitrokey.com/shop/product/nitropc-pro-523>`__ 
+     - `NitroPC Pro <https://web.archive.org/web/20231027112856/https://shop.nitrokey.com/shop/product/nitropc-pro-523>`__
      - :doc:`Certification details </user/hardware/certified-hardware/nitropc-pro/>`
    * - `NovaCustom <https://novacustom.com/>`__
      - `NV41 Series <https://novacustom.com/product/nv41-series/>`__
@@ -52,7 +52,7 @@ The current Qubes-certified models are listed below in reverse chronological ord
      - `Dasharo FidelisGuard Z690 <https://web.archive.org/web/20240917145232/https://shop.3mdeb.com/shop/open-source-hardware/dasharo-fidelisguard-z690-qubes-os-certified/>`__
      - :doc:`Certification details </user/hardware/certified-hardware/dasharo-fidelisguard-z690/>`
    * - `Nitrokey <https://www.nitrokey.com/>`__
-     - `NitroPad T430 <https://shop.nitrokey.com/shop/nitropad-t430-119>`__ 
+     - `NitroPad T430 <https://shop.nitrokey.com/shop/nitropad-t430-119>`__
      - :doc:`Certification details </user/hardware/certified-hardware/nitropad-t430/>`
    * - `Nitrokey <https://www.nitrokey.com/>`__
      - `NitroPad X230 <https://shop.nitrokey.com/shop/product/nitropad-x230-67>`__ 
@@ -60,7 +60,6 @@ The current Qubes-certified models are listed below in reverse chronological ord
    * - `Insurgo <https://insurgo.ca/>`__
      - `PrivacyBeast X230 <https://insurgo.ca/produit/qubesos-certified-privacybeast_x230-reasonably-secured-laptop/>`__ 
      - :doc:`Certification details </user/hardware/certified-hardware/insurgo-privacybeast-x230/>`
-   
 
 
 Become hardware certified

user/hardware/certified-hardware/dasharo-fidelisguard-z690.rst

@@ -11,8 +11,8 @@ The `Dasharo FidelisGuard Z690 <https://web.archive.org/web/20240917145232/https
 
 The `Dasharo FidelisGuard Z690 <https://web.archive.org/web/20240917145232/https://shop.3mdeb.com/shop/open-source-hardware/dasharo-fidelisguard-z690-qubes-os-certified/>`__ is a full desktop PC build that brings the `Dasharo <https://dasharo.com/>`__ open-source firmware distribution to the MSI PRO Z690-A DDR4 motherboard with Qubes OS preinstalled. The full configuration includes:
 
-.. list-table:: 
-   :widths: 14 14 
+.. list-table::
+   :widths: 14 14
    :align: center
    :header-rows: 1
 
@@ -30,7 +30,6 @@ The `Dasharo FidelisGuard Z690 <https://web.archive.org/web/20240917145232/https
      - SSD Intel 670p 512 GB M.2 2280 PCI-E x4 Gen3 NVMe
    * - Enclosure
      - SilentiumPC Armis AR1
-   
 
 
 |Photo of Dasharo FidelisGuard Z690 with open case|

user/hardware/certified-hardware/nitropad-x230.rst

@@ -6,7 +6,7 @@ NitroPad X230
 
 
 .. DANGER::
-      
+
       **Warning:** The CPU in this computer no longer receives microcode updates from Intel. Without microcode updates, Qubes OS cannot ensure that this computer is secure against CPU vulnerabilities. While this computer remains certified for Qubes OS Release 4, we recommend that prospective buyers consider a newer Qubes-certified computer instead.
 
 The `NitroPad X230 <https://shop.nitrokey.com/shop/product/nitropad-x230-67>`__ is :doc:`officially certified </user/hardware/certified-hardware/certified-hardware>` for Qubes OS Release 4.

user/hardware/certified-hardware/nitropc-pro.rst

@@ -6,11 +6,11 @@ NitroPC Pro
 
 
 .. warning::
-      
+
       **Note:** When configuring your NitroPC Pro 2 on the Nitrokey website, there is an option for a discrete graphics card (e.g., Nvidia GeForce RTX 4070 or 4090) in addition to integrated graphics (e.g., Intel UHD 770, which is always included because it is physically built into the CPU). NitroPC Pro 2 configurations that include discrete graphics cards are *not* Qubes-certified. The only NitroPC Pro 2 configurations that are Qubes-certified are those that contain *only* integrated graphics.
 
 .. warning::
-      
+
       **Note:** Only the “Dasharo TianoCore UEFI without Measured Boot, without Nitrokey” firmware option is certified. The “HEADS with Measured Boot, requires Nitrokey!” firmware option is *not* certified.
 
 The `NitroPC Pro <https://web.archive.org/web/20231027112856/https://shop.nitrokey.com/shop/product/nitropc-pro-523>`__ is :doc:`officially certified </user/hardware/certified-hardware/certified-hardware>` for Qubes OS Release 4.
@@ -19,8 +19,8 @@ The `NitroPC Pro <https://web.archive.org/web/20231027112856/https://shop.nitrok
 
 Here’s a summary of the main component options available for this mid-tower desktop PC:
 
-.. list-table:: 
-   :widths: 29 29 
+.. list-table::
+   :widths: 29 29
    :align: center
    :header-rows: 1
 
@@ -40,7 +40,6 @@ Here’s a summary of the main component options available for this mid-tower de
      - Wi-Fi 6E, 2400 Mbps, 802.11/a/b/g/n/ac/ax, Bluetooth 5.2
    * - Operating system (optional)
      - Qubes OS 4.1 or Ubuntu 22.04 LTS
-   
 
 
 Of special note for Qubes users, the NitroPC Pro features a combined PS/2 port that supports both a PS/2 keyboard and a PS/2 mouse simultaneously with a Y-cable (not included). This allows for full control of dom0 without the need for USB keyboard or mouse passthrough. Nitrokey also offers a special tamper-evident shipping method for an additional fee. With this option, the case screws will be individually sealed and photographed, and the NitroPC Pro will be packed inside a sealed bag. Photographs of the seals will be sent to you by email, which you can use to determine whether the case was opened during transit.

user/how-to-guides/how-to-install-software.rst

@@ -9,7 +9,7 @@ Qubes OS is effectively a “meta” operating system (OS) that can run almost a
 
 The following instructions explain how to permanently install new software in a template. There are different instructions for software from the default repositories and all other software. (If you’re not sure, try the default repositories first.)
 
-.. installing-software-from-default-repositories:
+.. _installing-software-from-default-repositories:
 
 Installing software from default repositories
 ---------------------------------------------
@@ -109,12 +109,12 @@ If things are still not working as expected:
 How to update software
 ----------------------
 
-Please see :doc:`how-to-update`.
+Please see :doc:`/user/how-to-guides/how-to-update`.
 
 Why don't templates have normal network access?
 -----------------------------------------------
 
-In order to protect you from performing risky activities in templates, they do not have normal network access by default. Instead, templates use an :ref:`updates-proxy` which allows you to install and update software using the distribution’s package manager over the proxy connection. **The updates proxy is already set up to work automatically out-of-the-box and requires no special action from you.** Most users should simply follow the normal instructions for :ref:`installing-software-from-default-repositories` and :doc:`updating <how-to-update>` software. If your software is not available in the default repositories, see `installing software from other sources <#installing-software-from-other-sources>`__.
+In order to protect you from performing risky activities in templates, they do not have normal network access by default. Instead, templates use an :ref:`updates-proxy` which allows you to install and update software using the distribution’s package manager over the proxy connection. **The updates proxy is already set up to work automatically out-of-the-box and requires no special action from you.** Most users should simply follow the normal instructions for :ref:`installing-software-from-default-repositories` and :doc:`updating </user/how-to-guides/how-to-update>` software. If your software is not available in the default repositories, see `installing software from other sources <#installing-software-from-other-sources>`__.
 
 Advanced
 --------
@@ -223,7 +223,7 @@ This is like the simple revert, except:
 
 - The saved revision of the volumes must be uncompromised. With the default ``revisions_to_keep=1`` for the root volume, you must **not** have started the template since the compromising action.
 
-.. updates-proxy:
+.. _updates-proxy:
 
 Updates proxy
 ^^^^^^^^^^^^^