merge upstream rst, add screenshots, rewrite how-to-edit-the-website, combine website and markdown-style-guide, enhance how-to-edit-the-rst-documentation and rst style guide, fix errors, added comments to conf.py, links to README & CONTRIBUTING

CONTRIBUTING.md

@@ -2,11 +2,11 @@
 
 Thank you for your interest in contributing to `qubes-doc`, the Qubes OS
 Project's dedicated documentation repository! Please see [how to edit the
-documentation](https://doc.qubes-os.org/developer/general/how-to-edit-the-documentation.html) for
+documentation](https://doc.qubes-os.org/developer/general/how-to-edit-the-rst-documentation.html) for
 detailed contribution instructions.
 
 In addition, please take a moment to read our [documentation style
-guide](https://doc.qubes-os.org/developer/general/documentation-style-guide.html) before
+guide](https://doc.qubes-os.org/developer/general/rst-documentation-style-guide.html) before
 contributing. These guidelines are important to maintaining high standards of
 quality, and following them will increase the likelihood that your contribution
 will be accepted.

README.md

@@ -1,11 +1,11 @@
 # Qubes OS Documentation
 
-Canonical URL: https://www.qubes-os.org/doc/
+Canonical URL: https://doc.qubes-os.org
 
 All [Qubes OS Project](https://github.com/QubesOS) documentation pages are
-stored as plain text files in this dedicated repository. By cloning and
+stored as plain reStructuredText files in this dedicated repository. By cloning and
 regularly pulling from this repo, users can maintain their own up-to-date
 offline copy of all Qubes documentation rather than relying solely on the Web.
 
 To contribute, please see [how to edit the
-documentation](https://doc.qubes-os.org/developer/general/how-to-edit-the-documentation.html).
+documentation](https://doc.qubes-os.org/developer/general/how-to-edit-the-rst-documentation.html).

conf.py

@@ -4,6 +4,7 @@ import os
 import sys
 from pathlib import Path
 
+# Append the path to custom extensions
 sys.path.append(str(Path('_ext').resolve()))
 
 # For the full list of options, see the documentation:
@@ -29,13 +30,14 @@ release = '4.2.4'
 # -- General configuration ---------------------------------------------------
 
 extensions = [
-  'sphinx.ext.autosectionlabel',
-  'sphinxnotes.strike',
-  'sphinx_reredirects',
-  'sphinxext.opengraph',
-  'youtube_frame',
+  'sphinx.ext.autosectionlabel',  # Automatically generate section labels
+  'sphinxnotes.strike', # Add strike-through text support
+  'sphinx_reredirects', # Manage redirects in the documentation
+  'sphinxext.opengraph', # Add Open Graph meta tags for social media sharing
+  'youtube_frame', # Embed YouTube videos
 ]
 
+# Redirects for specific URLs as fall back
 redirects = {
     "user/hardware/hcl":
         "https://www.qubes-os.org/hcl/",
@@ -50,12 +52,15 @@ redirects = {
 
 # -- -- Options for highlighting ---------------------------------------------
 
+# Disable syntax highlighting
 highlight_language = 'none'
 
+# Set the Pygments style for syntax highlighting
 pygments_style = 'sphinx'
 
 # -- -- Options for source files ---------------------------------------------
 
+# Patterns to exclude from the source directory
 exclude_patterns = [
   '_*',
   '**/.*',
@@ -92,10 +97,12 @@ linkcheck_anchors = False
 linkcheck_ignore = [r'^https?://[^/\s]+\.onion']
 
 # -- Extensions configuration ------------------------------------------------
-
+# Prefix section labels with the document name
 autosectionlabel_prefix_document = True
 
+# Open Graph image for social media sharing
 ogp_image = "https://www.qubes-os.org/attachment/icons/qubes-logo-icon-name-slogan-fb.png"
+# Disable Open Graph image alt text
 ogp_image_alt = False
 
 # -- HTML configuration ------------------------------------------------------
@@ -113,6 +120,7 @@ html_context = {
 
 # -- -- Options for internationalisation -------------------------------------
 
+# Directories containing translation files
 locale_dirs = ['_translated']
 
 gettext_compact = False
@@ -121,6 +129,7 @@ gettext_uuid = True
 
 # -- -- Options for markup ---------------------------------------------------
 
+# Define a block of reusable reStructuredText (reST) snippets, warnings etc. that Sphinx automatically appends to every source file before it is parsed
 rst_epilog = """
 .. |debian-codename| replace:: bookworm
 .. |debian-version| replace:: 12

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

@@ -2,7 +2,7 @@
 How to edit the documentation
 =============================
 
-The Qubes OS documentation is stored as reStructuredText (rST) files in
+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.
@@ -13,19 +13,23 @@ We use `Sphinx <https://www.sphinx-doc.org/>`__ for building and
     :align: center
 
 
-By cloning and regularly pulling from this repo, users can maintain their
+By cloning and regularly pulling from `qubes-doc <https://github.com/QubesOS/qubes-doc>`__ repository, users can maintain their
 own up-to-date offline copy of the Qubes documentation rather than
 relying solely on the web. EPUB or PDF versions of Qubes OS documenation can also
-be downloaded from `doc.qubes-os.org <https://doc.qubes-os.org/en/latest/>`__.
+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 add draft pull request screenshot
 
 The documentation is a volunteer community effort. People like you are
 constantly working to make it better. If you notice something that can
 be fixed or improved, please follow the steps below to open a pull
 request!
 
-If you wish to submit a PR for the website, please refer to `how to edit the Markdown pages <https://www.qubes-os.org/doc/how-to-edit-the-website/>`__.
-
 
 How to submit a pull request
 ============================
@@ -38,7 +42,7 @@ GitHub account.
 
 A few notes before we get started:
 
--  Since Qubes is a security-oriented project, every documentation change will be :ref:`reviewed <developer/general/how-to-edit-the-documentation:security>` before it’s accepted. This allows us to maintain quality control and protect our users.
+-  Since Qubes is a security-oriented project, every documentation change will be :ref:`reviewed <developer/general/how-to-edit-the-rst-documentation: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:`reStrucutredText Style Guide </developer/general/rst-documentation-style-guide/>`.
 
@@ -46,7 +50,7 @@ A few notes before we get started:
 
 -  Alternatively, you may already have written content that doesn’t conform to these guidelines, but you’d be willing to modify it so that it does. In this case, you can still submit it by following the instructions below. Just make a note in your pull request (PR) that you’re aware of the changes that need to be made and that you’re just asking for the content to be reviewed before you spend time making those changes.
 
--  Finally, if you’ve written something that doesn’t belong in qubes-doc but that would be beneficial to the Qubes community, please consider adding it to the :ref:`external documentation <developer/general/documentation-style-guide:core vs external documentation>`.
+-  Finally, if you’ve written something that doesn’t belong in qubes-doc but that would be beneficial to the Qubes community, please consider adding it to the :ref:`external documentation <developer/general/rst-documentation-style-guide:core vs. external documentation>`.
 
 (**Advanced users:** If you’re already familiar with GitHub or wish to
 work from the command line, you can skip the rest of this section. All
@@ -58,40 +62,42 @@ Ok, let’s begin. Every documentation page has a “Edit on GitHub” link.
 
 |page-source-button|
 
-When you click on it, you’ll be taken to the source file — a reStructuredText (``.rst``) file — on GitHub. On this page, there will be a
+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
 
-
-
-If you are not logged in you can click on login 
-
-|github-edit| 
-
-and you’ll be prompted to sign in with your GitHub username and password (if
-you aren’t already logged in). You can also create a free account from
+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.
+You can also create a free account from
 here.
 
 |github-sign-in|
 
 If this is your first contribution to the documentation, you need to
-“fork” the repository (make your own copy). It’s easy — just click the
-big green button on the next page. This step is only needed the first
-time you make a contribution.
-
-TODO
+:guilabel:`fork` the repository (make your own copy).
 
 |fork1|
 
+It’s easy — just click the
+green :guilabel:`Create fork` on the next page. This step is only needed the first
+time you make a contribution.
+
+
 |fork2|
 
+Now you can make your modifications.
+
 |fork3|
 
-Now you can make your modifications. You can also preview the changes to
-see how they’ll be formatted by clicking the “Preview changes” tab. If
-you want to add images, please see :ref:`How to add images <developer/general/how-to-edit-the-rst-documentation:how to add images>`. 
-Please see :ref:`how to render the documentation on your local machine <building-the-rst-documentation-locally>`
+You can also preview the changes by clicking the :guilabel:`Preview changes` tab.
+
+If you want to add images, read :ref:`how_to_add_images`. 
+and refer to :ref:`build_locally`
 if you want to locally verify that everything looks correct before submitting any changes.
 
 
@@ -99,32 +105,29 @@ 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
-“Propose file change”.
+:guilabel:`Propose file change`.
 
 |commit|
 
 After that, you’ll see exactly what modifications you’ve made. At this
 stage, those changes are still in your own copy of the documentation
 (“fork”). If everything looks good, send those changes to us by pressing
-the “Create pull request” button.
+the :guilabel:`Create pull request` button.
 
-|pull-request|
 
 |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
-“Create pull request” button again. However, if you’re not ready for
+:guilabel:`Create pull request` button again. However, if you’re not ready for
 your PR to be reviewed or merged yet, please
 `make a draft PR instead <https://github.blog/2019-02-14-introducing-draft-pull-requests/>`__.
 
-TODO file:///home/user/QubesIncoming/qubes-os/rst-cycle.drawio
-
 |pull-request-confirm|
 
 If any of your changes should be reflected in the :doc:`documentation index (a.k.a. table of contents) </index>` — for example, if you’re adding a
 new page, changing the title of an existing page, or removing a page —
-please see :ref:`How to edit the documentation index <developer/general/how-to-edit-the-rst-documentation:how to edit the documentation index>`.
+please see :ref:`edit_doc_index`.
 
 That’s all! We will review your changes. If everything looks good, we’ll
 pull them into the official documentation. Otherwise, we may have some
@@ -133,52 +136,58 @@ questions for you, which we’ll post in a comment on your pull request.
 can’t accept your pull request, we’ll post a comment explaining why we
 can’t.
 
-|done|
 
-TODO copied
+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/>`__:
+
+|pull-request-builds|
+
+There you can view the rendered docs or inspect the logs for errors:
+
+|pull-request-build|
+
+You can also just head straight to the following url: ``https://qubes-doc--<PR-NUMBER>.org.readthedocs.build/en/<PR-NUMBER>/``.
 
 
 Tips & Tricks
 -------------
 
 - Pull upstream changes into your fork regularly. Diverging too far from main can be cumbersome to update at a later stage.
-
 - To pull in upstream changes:
 
-
-.. code:: console
+  .. code:: console
 
    $ git remote add upstream https://github.com/QubesOS/qubes-doc.git
    $ git fetch upstream
 
 - Check the log and the current changes, before merging:
 
-.. code:: console
+  .. code:: console
+
    $ git log upstream/main
 
-Then merge the changes that you fetched:
+- Then merge the changes that you fetched:
+
+  .. code:: console
 
-.. code:: console
    $ git merge upstream/main
 
-
-TODO 
-1. sphinx-build
-2. logs
-Any pull request that fails the sphinx-build can be seen at 
-
 Keep your pull requests limited to a single issue, pull requests should be as atomic as possible. 
 
+.. _edit_doc_index:
 
+TL;DR: How to edit the documentation index
+==========================================
 
-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` contains information about the hierarchy between the files in the documentation and/or
+:file:`index.rst` contains information about the hierarchy between the files in the documentation and/or
 the connection between them. `toctree <https://www.sphinx-doc.org/en/master/usage/restructuredtext/directives.html#directive-toctree>`__
 is the rST directive which defines the table of contents.
 
@@ -198,9 +207,12 @@ submit an associated pull request against this file.
 
 Please always be mindful that rST syntax is sensitive to indentation (3 spaces)!
 
+.. _how_to_add_images:
 
-How to add images
-=================
+TL;DR: How to add images
+========================
+
+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/>`.
 
 Images reside inside the `qubes-doc repository <https://github.com/QubesOS/qubes-doc/>`__ in the directory `attachment/doc <https://github.com/QubesOS/qubes-doc/tree/rst/attachment/doc>`__.
 
@@ -215,12 +227,16 @@ To add an image to a page, use the following syntax:
 If you want to add a caption to the image, you may do so using the ``caption`` option of the `figure directive <https://docutils.sourceforge.io/docs/ref/rst/directives.html#figure>`__.
 Another way without a caption is to use the `image directive <https://docutils.sourceforge.io/docs/ref/rst/directives.html#image>`__.
 
-Then, add your image(s) in a the `attachment/doc folder` in the `qubes-doc <https://github.com/QubesOS/qubes-doc>`__
+Then, add your image(s) in a the :file:`attachment/doc` folder in the `qubes-doc <https://github.com/QubesOS/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-referencing
-=================
+.. _cross_refrencing:
+
+TL;DR: Cross-referencing
+========================
+
+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/>`.
 
 When referencing to an existing RST file use the ``:doc:`` `role <https://www.sphinx-doc.org/en/master/usage/referencing.html#role-doc>`__ as in
 
@@ -250,20 +266,11 @@ 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"?>`.
 
-Viewing your pull request on RTD
-======================================
 
-diagram TODO add the PR automatical build on RTD section later on as 
-To view your pull request on RTD you can go to Qubes OS builds on `RTD <https://app.readthedocs.org/projects/qubes-doc/builds/>`__.
+TODO: label of sections and referencing them
 
 
-|pull-request-builds|
-
-|pull-request-build|
-
-TODO
-
-You can also just head to the following url ``https://qubes-doc--<PR-NUMBER>.org.readthedocs.build/en/<PR-NUMBER>/``.
+.. _build_locally:
 
 Building the rST documentation locally
 ======================================
@@ -282,164 +289,178 @@ Using venv
 ----------
 
 
-Install needed packages and clone the repository.
+1. **Install needed packages and clone the repository**
 
-.. code-block:: console
+  .. code-block:: console
 
     $ sudo apt install git python3-dev python3.11-venv
     $ git clone https://github.com/QubesOS/qubes-doc.git
 
-
-Install Sphinx Tools and Build Qubes OS Documentation
------------------------------------------------------
-
-
-To install Sphinx and perform linting and link checking for an existing project, follow these steps:
-
-1.  **Install Sphinx and Required Extensions**
+2.  **Install Sphinx and Required Extensions**
 
    Install Sphinx and the necessary extensions (`sphinx-autobuild`, `sphinx-lint`) using `pip`.
 
-.. code-block:: console
+    .. code-block:: console
 
-   $ python -m venv .q_env
-   $ source .q_env/bin/activate
-   $ pip install -r qubes-doc/requirements.txt
-   $ pip install sphinx sphinx-lint sphinx-autobuild
+     $ python -m venv .q_env
+     $ source .q_env/bin/activate
+     $ pip install -r qubes-doc/requirements.txt
+     $ pip install sphinx sphinx-lint sphinx-autobuild
 
 
-2.  **Verify Installation**
+3.  **Verify Installation**
 
-.. code-block:: console
+    .. code-block:: console
 
-   $ sphinx-build --version
+     $ sphinx-build --version
 
 
-3.  **Build Documentation**
+4.  **Build Documentation**
 
    Use `sphinx-build` with the `-v` (verbose) flag to generate detailed output during the build process.
 
-.. code-block:: console
+    .. code-block:: console
 
-   $ sphinx-build -v -b html qubes-doc _build/html
+     $ sphinx-build -v -b html qubes-doc _build/html
 
 
-The build command specifies the source directory (`qubes-doc`), the output directory (`_build/html`), and the builder (`html`)
-and will process all source files in the `qubes-doc` directory,
-generate HTML output in the `_build/html` directory, and print detailed build information to the console.
-Pay attention to errors and warning in the output!
-Please do not introduce any new warnings and fix all errors.
+   The build command specifies the source directory (:file:`qubes-doc`), the output directory (:file:`_build/html`), and the builder (`html`)
+   and will process all source files in the :file:`qubes-doc` directory,
+   generate HTML output in the :file:`_build/html` directory, and print detailed build information to the console.
+   Pay attention to errors and warning in the output!
+   Please do not introduce any new warnings and fix all errors.
 
-4.  **Run Linting**
+5.  **Run Linting**
 
    The `sphinx-lint` extension checks for common issues like missing references, invalid directives,
    or formatting errors.
 
-.. code-block:: console
+    .. code-block:: console
 
-   $ sphinx-lint qubes-doc
+     $ sphinx-lint qubes-doc
 
 
-5.  **Run Link Checking**
+6.  **Run Link Checking**
 
    The `sphinx-linkcheck` extension verifies the validity of all external and internal links.
 
-   The results will be written to the `_build/linkcheck` directory with a detailed report in `output.txt` or `output.json` files
+   The results will be written to the :file:`_build/linkcheck` directory with a detailed report in :file:`output.txt` or :file:`output.json` files
    of all checked links and their status (e.g., OK, broken).
 
-.. code-block:: console
+    .. code-block:: console
 
-   $ sphinx-build -b linkcheck qubes-doc _build/linkcheck
+     $ sphinx-build -b linkcheck qubes-doc _build/linkcheck
 
 
-6.  **Use sphinx-autobuild for development**
+7.  **Use sphinx-autobuild for development**
 
    For an active development workflow, you can use `sphinx-autobuild` to automatically rebuild the documentation
    and refresh browser whenever a file is saved. `sphinx-autobuild` starts a web server at `http://127.0.0.1:8000`,
-   automatically rebuilds the documentation and reloads the browser tab when changes are detected in the `qubes-doc` directory.
-
-.. code-block:: console
-
-   $ sphinx-autobuild qubes-doc _build/html
+   automatically rebuilds the documentation and reloads the browser tab when changes are detected in the :file:`qubes-doc` directory.
 
+    .. code-block:: console
 
+     $ sphinx-autobuild qubes-doc _build/html
 
 
 Using poetry
 ------------
 
 
-`Install poetry <https://python-poetry.org/docs/#installation>`__ and git and clone the repository.
+1. `Install poetry <https://python-poetry.org/docs/#installation>`__ and git and clone the repository.
 A `pyproject.toml` file is provided.
 
-.. code-block:: console
+  .. code-block:: console
 
     $ sudo apt install git
     $ curl -sSL https://install.python-poetry.org | python3 -
     $ git clone https://github.com/QubesOS/qubes-doc.git
+    $ cd qubes-doc
+    $ poetry install
 
 
-1.  **Build Documentation**
+2.  **Build Documentation**
 
    Use `sphinx-build` with the `-v` (verbose) flag to generate detailed output during the build process.
-   The build command specifies the source directory (`qubes-doc`), the output directory (`_build/html`), and the builder (`html`).
+   The build command specifies the source directory (:file:`qubes-doc`), the output directory (:file:`_build/html`), and the builder (`html`).
 
-.. code-block:: console
+    .. code-block:: console
 
-   $ poetry run sphinx-build -v -b html qubes-doc _build/html
+     $ poetry run sphinx-build -v -b html ../qubes-doc _build/html
 
-This command will process all source files in the `qubes-doc` directory,
-generate HTML output in the `_build/html` directory, and print detailed build information to the console.
-Pay attention to errors and warning in the output!
-Please do not introduce no new warning and fix all errors.
+   This command will process all source files in the :file:`qubes-doc` directory,
+   generate HTML output in the :file:`_build/html` directory, and print detailed build information to the console.
+   Pay attention to errors and warning in the output!
+   Please do not introduce no new warning and fix all errors.
 
-2.  **Run Linting**
+3.  **Run Linting**
 
    The `sphinx-lint` extension checks for common issues like missing references, invalid directives,
    or formatting errors. Run the linting step using the `sphinx-lint` command.
 
-.. code-block:: console
+    .. code-block:: console
 
-   $ poetry run sphinx-lint qubes-doc
+     $ poetry run sphinx-lint ../qubes-doc
 
 
-3.  **Run Link Checking**
+4.  **Run Link Checking**
 
    The `sphinx-linkcheck` extension verifies the validity of all external and internal links.
 
-   The results will be written to the `_build/linkcheck` directory with a detailed report in `output.txt` or `output.json` files
+   The results will be written to the :file:`_build/linkcheck` directory with a detailed report in :file:`output.txt` or :file:`output.json` files
    of all checked links and their status (e.g., OK, broken, timeout).
 
-.. code-block:: console
+    .. code-block:: console
 
-   $ poetry run sphinx-build -b linkcheck qubes-doc _build/linkcheck
+     $ poetry run sphinx-build -b linkcheck ../qubes-doc _build/linkcheck
 
-4.  **Use sphinx-autobuild for development**
+5.  **Use sphinx-autobuild for development**
 
    For an active development workflow, you can use `sphinx-autobuild` to automatically rebuild the documentation
    and refresh browser whenever a file is saved. `sphinx-autobuild` starts a web server at `http://127.0.0.1:8000`,
-   automatically rebuilds the documentation and reloads the browser tab when changes are detected in the `qubes-doc` directory.
+   automatically rebuilds the documentation and reloads the browser tab when changes are detected in the :file:`qubes-doc` directory.
 
 
-.. code-block:: console
+    .. code-block:: console
 
-   $ poetry run sphinx-autobuild qubes-doc _build/html
+     $ poetry run sphinx-autobuild ../qubes-doc _build/html
 
 
+You can also use `uv <https://docs.astral.sh/uv/getting-started/>`__ as you wish.
+
 
 Editor
 ------
 
-
 An editor you can use is `ReText <https://github.com/retext-project/retext>`__ but any editor would do.
 
 
 .. code-block:: console
 
+   $ python3 -m venv myenv
+   $ source myenv/bin/activate
    $ sudo apt install libxcb-cursor0
    $ pip3 install ReText
 
 
+Configuration
+-------------
+
+Qubes-doc directory contains a build configuration file named :file:`conf.py`, used by Sphinx
+to define `input and output behaviour <https://www.sphinx-doc.org/en/master/usage/configuration.html>`__.
+It contains settings and extensions that define how the documentation will be generated.
+
+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>`__
+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>`__.
+
+
 Security
 ========
 
@@ -474,7 +495,7 @@ If you have a question about something you read in the documentation or
 about how to edit the documentation, 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
 documentation should be fixed or improved, please
-:ref:`contribute <developer/general/how-to-edit-the-documentation:how to submit a pull request>` the change yourself. To
+:ref:`contribute <developer/general/how-to-edit-the-rst-documentation:how to submit a pull request>` the change yourself. To
 report an issue with the documentation, please follow our standard
 :doc:`issue reporting guidelines </introduction/issue-tracking>`. (If you report an
 issue with the documentation, you will likely be asked to submit a pull
@@ -483,16 +504,16 @@ you are not willing or able to do so.)
 
 
 .. |page-source-button| image:: /attachment/doc/doc-pr_01_page-source-button-rtd.png
-.. |github-edit| image:: /attachment/doc/doc-pr_02_github-edit-rts.png
-.. |github-sign-in| image:: /attachment/doc/doc-pr_03_sign-in-rts.png
-.. |fork1| image:: /attachment/doc/doc-pr_04_fork-rts1.png
-.. |fork2| image:: /attachment/doc/doc-pr_04_fork-rts2.png
-.. |fork3| image:: /attachment/doc/doc-pr_04_fork-rts3.png
+.. |github-edit| image:: /attachment/doc/doc-pr_02_github-edit-rst.png
+.. |github-sign-in| image:: /attachment/doc/doc-pr_03_sign-in-rst.png
+.. |fork1| image:: /attachment/doc/doc-pr_04_fork-rst1.png
+.. |fork2| image:: /attachment/doc/doc-pr_04_fork-rst2.png
+.. |fork3| image:: /attachment/doc/doc-pr_04_fork-rst3.png
 .. |edit| image:: /attachment/doc/doc-pr_05_edit-rst.png
 .. |commit| image:: /attachment/doc/doc-pr_06_commit-msg-rst.png
-.. |pull-request| image:: /attachment/doc/doc-pr_07_review-changes.png
-.. |pull-request-confirm| image:: /attachment/doc/doc-pr_09_create-pr-rts.png
-.. |draft-pull-request-confirm| image:: /attachment/doc/doc-pr_09_create-dpr-rts.png
+.. |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
 .. |pull-request-builds| image:: /attachment/doc/doc-pr_10_view-pr-rtd.png
 .. |pull-request-build| image:: /attachment/doc/doc-pr_11_view-pr-rtd.png
 .. |done| image:: /attachment/doc/doc-pr_09_done.png
+.. |epub-pdf| image:: /attachment/doc/rst-rtd-epub-pdf.png

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

@@ -3,139 +3,217 @@ How to edit the website
 =======================
 
 
-*Also see the* :doc:`documentation style guide </developer/general/documentation-style-guide>` *.*
+*Also see the* :doc:`Website style guide </developer/general/website-style-guide>`.
 
-Qubes OS documentation pages are stored as plain text Markdown files in the `qubes-doc <https://github.com/QubesOS/qubes-doc>`__ repository. By cloning and regularly pulling from this repo, users can maintain their own up-to-date offline copy of all Qubes documentation rather than relying solely on the web.
+The Qubes OS website content is stored in the `qubesos.github.io <https://github.com/QubesOS/qubesos.github.io>`__ repository and its submodules.
+By cloning and regularly pulling from this repo, users can maintain their own up-to-date offline copy of the Qubes OS website rather than relying solely on the web.
 
-The documentation is a volunteer community effort. People like you are constantly working to make it better. If you notice something that can be fixed or improved, please follow the steps below to open a pull request!
+This guide refers only to the hosted website on `qubes-os.org <https://qubes-os.org>`__.
+It was the reference point before the documentation was converted from
+Markdown to reStructuredText and remains as a guide if you want to contribute
+to the Qubes OS website.
+If you want to contribute to the Qubes OS documentation, please visit :doc:`How to edit the documentation </developer/general/how-to-edit-the-rst-documentation>`.
 
 How to submit a pull request
 ----------------------------
 
+We keep all relevant files in `qubesos.github.io <https://github.com/QubesOS/qubesos.github.io>`__, as well as
+`qubes-attachment <https://github.com/QubesOS/qubes-attachment>`__,
+`qubes-hcl <https://github.com/QubesOS/qubes-hcl>`__ and `qubes-posts <https://github.com/QubesOS/qubes-posts>`__ - dedicated Git repositories
+hosted on `GitHub <https://github.com/>`__.
 
-We keep all the documentation in `qubes-doc <https://github.com/QubesOS/qubes-doc>`__, a dedicated Git repository hosted on `GitHub <https://github.com/>`__. Thanks to GitHub’s easy web interface, you can edit the documentation even if you’re not familiar with Git or the command line! All you need is a free GitHub account.
-
-A few notes before we get started:
-
-- Since Qubes is a security-oriented project, every documentation change will be `reviewed <#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:`documentation style guide </developer/general/documentation-style-guide>`.
+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.
+- 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>`.
 
-- Alternatively, you may already have written content that doesn’t conform to these guidelines, but you’d be willing to modify it so that it does. In this case, you can still submit it by following the instructions below. Just make a note in your pull request (PR) that you’re aware of the changes that need to be made and that you’re just asking for the content to be reviewed before you spend time making those changes.
+For an example how to submit a pull request please refer to the example given in :ref:`How to submit a pull request <developer/general/how-to-edit-the-rst-documentation:how to submit a pull request>` with the documentation.
 
-- Finally, if you’ve written something that doesn’t belong in qubes-doc but that would be beneficial to the Qubes community, please consider adding it to the :ref:`external documentation <developer/general/documentation-style-guide:core vs. external documentation>`.
+The Qubes OS website
+--------------------
+
+The Qubes OS site is generated with `Jekyll <https://jekyllrb.com/>`__, a static‑site engine that transforms Markdown, HTML, and data files into a fully rendered, deploy‑ready website.
+
+These are the relevant repositories:
+
+- the main `qubesos.github.io <https://github.com/QubesOS/qubesos.github.io>`__, as well as its submodules:
+- `qubes-attachment <https://github.com/QubesOS/qubes-attachment>`__,
+- `qubes-hcl <https://github.com/QubesOS/qubes-hcl>`__ and
+- `qubes-posts <https://github.com/QubesOS/qubes-posts>`__.
 
 
+The contents of the `qubes-posts <https://github.com/QubesOS/qubes-posts>`__ repository is reflected in the `News section <https://www.qubes-os.org/news/>`__:
 
-(**Advanced users:** If you’re already familiar with GitHub or wish to work from the command line, you can skip the rest of this section. All you need to do to contribute is to `fork and clone <https://guides.github.com/activities/forking/>`__ the `qubes-doc <https://github.com/QubesOS/qubes-doc>`__ repo, make your changes, then `submit a pull request <https://help.github.com/articles/using-pull-requests/>`__.)
+|news-section|
 
-Ok, let’s begin. Every documentation page has a “Page Source on GitHub” button. Depending on the size of your screen, it may either be on the side (larger screens) or on the bottom (smaller screens).
+This repository is maintained by the Qubes OS team and serves the purpose of announcing relevant project news. This repository and its contents should be left as is.
 
-|page-source-button|
+The contents of the `qubes-hcl <https://github.com/QubesOS/qubes-hcl>`__ repository can be seen in the `Hardware Compatibility List (HCL) table <https://www.qubes-os.org/hcl/>`__:
 
-When you click on it, you’ll be taken to the source file — usually a Markdown (``.md``) file — on GitHub. On this page, there will be a button to edit the file.
+|hcl-section|
 
-|github-edit|
+This repository is also maintained by the Qubes OS team and its contents should be left as is. Of course you can :ref:`generate and submit a Hardware Compatibility List (HCL) report <user/hardware/how-to-use-the-hcl:generating and submitting new reports>` at any time.
 
-You’ll be prompted to sign in with your GitHub username and password (if you aren’t already logged in). You can also create a free account from here.
-
-|github-sign-in|
-
-If this is your first contribution to the documentation, you need to “fork” the repository (make your own copy). It’s easy — just click the big green button on the next page. This step is only needed the first time you make a contribution.
-
-|fork|
-
-Now you can make your modifications. You can also preview the changes to see how they’ll be formatted by clicking the “Preview changes” tab. If you want to add images, please see `How to add images <#how-to-add-images>`__. If you’re making formatting changes, please `render the site locally <https://github.com/QubesOS/qubesos.github.io#instructions>`__ to verify that everything looks correct before submitting any changes.
-
-|edit|
-
-Once you’re finished, describe your changes at the bottom and click “Propose file change”.
-
-|commit|
-
-After that, you’ll see exactly what modifications you’ve made. At this stage, those changes are still in your own copy of the documentation (“fork”). If everything looks good, send those changes to us by pressing the “Create pull request” button.
-
-|pull-request|
-
-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 “Create pull request” button again. However, if you’re not ready for your PR to be reviewed or merged yet, please `make a draft PR instead <https://github.blog/2019-02-14-introducing-draft-pull-requests/>`__.
-
-|pull-request-confirm|
-
-If any of your changes should be reflected in the :doc:`documentation index (a.k.a. table of contents) </index>` — for example, if you’re adding a new page, changing the title of an existing page, or removing a page — please see `How to edit the documentation index <#how-to-edit-the-documentation-index>`__.
-
-That’s all! We will review your changes. If everything looks good, we’ll pull them into the official documentation. Otherwise, we may have some questions for you, which we’ll post in a comment on your pull request. (GitHub will automatically notify you if we do.) If, for some reason, we can’t accept your pull request, we’ll post a comment explaining why we can’t.
-
-|done|
-
-How to edit the documentation index
------------------------------------
+The `qubes-attachment <https://github.com/QubesOS/qubes-hcl>`__ repository contains images and files that are used by or referenced in the website.
+Here you can add new images if needed.
+Then, submit your image(s) in a separate pull request to the `qubes-attachment <https://github.com/QubesOS/qubes-attachment>`__ repository using the same path and filename. This is the only permitted way to include images. Do not link to images on other websites.
 
 
-The source file for the :doc:`documentation index (a.k.a. table of contents) </index>` is `doc-index.yml <https://github.com/QubesOS/qubesos.github.io/blob/master/_data/doc-index.yml>`__.
-
-Editing this file will change what appears on the documentation index. If your pull request (PR) adds, removes, or edits anything that should be reflected in the documentation index, please make sure you also submit an associated pull request against this file.
-
-How to add images
------------------
+Quick intro to Jekyll
+---------------------
 
 
-To add an image to a page, use the following syntax in the main document (see :ref:`here <developer/general/documentation-style-guide:image linking>` for why this syntax is important).
+`Jekyll <https://jekyllrb.com/>`__ is a static‑site generator that turns plain‑text files (Markdown, HTML, YAML, etc.) into a full website you can host on GitHub Pages. It works by:
+
+- *Reading data*: YAML front‑matter in :file:`pages/_posts` and files under :file:`_data` give variables you can reuse.
+- *Applying layouts*: HTML layout files wrap your content, letting you keep a consistent header/footer, navigation, etc.
+- *Processing includes*: Reusable snippets (HTML/Jinja‑style) can be dropped into pages.
+- *Compiling assets*: SASS/SCSS files become CSS, JavaScript is copied as‑is.
+- *Generating the output*: All source files are rendered into a :file:`_site` folder that contains the ready‑to‑serve static files.
+
+
+The main `qubesos.github.io <https://github.com/QubesOS/qubesos.github.io>`__ contains the following directories:
 
 .. code:: bash
 
-      [![Image Title](/attachment/doc/image.png)](/attachment/doc/image.png)
+  ├── data          # ← YAML files with key‑value pairs used throughout the site
+  │   └── *.yml     # e.g. site settings, navigation menus
+  │
+  ├── _doc          # ← Empty Markdown documentation files (previously a submodule “qubes‑doc”)
+  │   └── *.md      # with redirects to RTD
+  │
+  ├── _hcl          # ← “qubes‑hcl” submodule – custom content for HCL pages
+  │   └── ...       #
+  │
+  ├── _includes     # ← Reusable HTML/Jinja snippets
+  │   └── *.html    # include with {% include filename.html %} in Markdown or layouts
+  │
+  ├── _layouts      # ← Page templates that wrap content
+  │   └── *.html    # e.g. default.html, news.html, hcl.html – edit to change overall page structure
+  │
+  ├── _posts        # ← “qubes‑post” submodule – blog‑style entries
+  │   └── *_*.md    # each post has YAML front‑matter
+  │
+  ├── _sass         # ← Source SASS/SCSS files
+  │   └── *.scss    #
+  │
+  ├── _utils        # ← Helper scripts or small utilities used by the site
+  │   └── *.py/.sh  # usually not touched unless you need custom build steps
+  │
+  ├── attachment    # ← “qubes‑attachment” submodule – extra downloadable files
+  │   └── *.*       # place PDFs, images, etc. that you want linked from the site
+  │
+  ├── css           # ← CSS files
+  │   └── *.css     #
+  │
+  ├── fontawesome   # ← Font Awesome CSS and font files
+  │   └── *.css/.ttf
+  │
+  ├── fonts         # ← Additional font files used by the site
+  │   └── *.woff/.ttf
+  │
+  ├── js            # ← JavaScript assets
+  │   └── *.js      # edit to add or modify interactive behaviour
+  │
+  ├── news          # ← Templates for generating news‑type content
+  │   └── *.md      # often paired with a layout (e.g., news.html)
+  │
+  └── pages         # ← Stand‑alone pages (donate, team, about, etc.)
+    └── *.md/.html  # each file becomes a page at /<filename>/
+
+How to edit the website
+-----------------------
+
+.. list-table::
+   :header-rows: 1
+   :widths: 20 30 50
+   :align: center
+
+   * - Goal
+     - Where to edit
+     - Typical steps
+   * - Change site‑wide text (e.g., site title, navigation)
+     - ``_data/*.yml``, ``_config.yml``
+     - Update the key/value pair, then rebuild.
+   * - Modify the look of all pages
+     - ``_layouts/*.html`` and/or ``_sass/*.scss``
+     - Edit the HTML skeleton or SASS variables, then run ``jekyll serve`` to preview.
+   * - Insert a reusable component (e.g., a call‑out box)
+     - ``_includes/*.html``
+     - Create the snippet, then reference it with ``{% include snippet.html %}`` in any page or post.
+   * - Add a new static asset (image, PDF)
+     - ``attachment/`` (`qubes-attachment <https://github.com/QubesOS/qubes-attachment>`__)
+     - Drop the file there and link to it using a relative URL.
+   * - Update JavaScript behavior
+     - ``js/*.js``
+     - Edit the script, ensure it’s referenced in the appropriate layout or page.
 
 
+How to serve the website locally
+--------------------------------
 
-Then, submit your image(s) in a separate pull request to the `qubes-attachment <https://github.com/QubesOS/qubes-attachment>`__ repository using the same path and filename. This is the only permitted way to include images. Do not link to images on other websites.
+You can serve the website offline on your local machine by following `these instructions <https://github.com/QubesOS/qubesos.github.io#instructions>`__ or the instructions below.
+This can be useful for making sure that your changes render the way you expect, especially when your changes affect formatting, images, tables, styling, etc.
 
-Serving the website locally
----------------------------
+1. Create a template qube:
+
+.. code:: console
+
+  $ qvm-clone debian-12-minimal jekyll-tvm
+
+2. Install packages:
+
+.. code:: console
+
+  $ apt install qubes-core-agent-networking
+  $ apt install ruby-full build-essential zlib1g-dev vim
+  $ apt install qubes-core-agent-passwordless-root
+  $ apt install firefox-esr git
 
 
-You can serve the website offline on your local machine by following `these instructions <https://github.com/QubesOS/qubesos.github.io#instructions>`__. This can be useful for making sure that your changes render the way you expect, especially when your changes affect formatting, images, tables, styling, etc.
+3. Create a ``jekyll-app-vm`` based on the ``jekyll-tvm`` template, install and configure in ``jekyll-app-vm``:
+
+.. code:: console
+
+  $ echo '# Install Ruby Gems to ~/gems' >> ~/.bashrc
+  $ echo 'export GEM_HOME="$HOME/gems"' >> ~/.bashrc
+  $ echo 'export PATH="$HOME/gems/bin:$PATH"' >> ~/.bashrc
+  $ source ~/.bashrc
+  $ gem install jekyll bundler
+  $ find . -name gem
+  $ bundle config set --local path '/home/user/.local/share/gem/'
+  $ git clone -b new-main --recursive https://github.com/QubesOS/qubesos.github.io.git; cd qubesos.github.io/
+  $ bundle install
+  $ bundle exec jekyll serve --incremental
+
+You can view the local site at `http://localhost:4000 <http://localhost:4000>`__.
+
+Quick checklist for a typical edit
+----------------------------------
+
+- Locate the right folder – use the table above to know where the content lives.
+- Edit the file – Markdown for content, HTML/SASS for layout/style, YAML for data.
+- Run a local build to verify the change looks correct.
+- Commit & push – include a clear commit message describing the edit.
+- Create a Pull Request
+
+Feel free to ask if you need more detail on any specific folder or on how to set up the development environment!
 
 Security
 --------
 
-
 *Also see:* :ref:`Should I trust this website? <introduction/faq:should i trust this website?>`
 
-All pull requests (PRs) against `qubes-doc <https://github.com/QubesOS/qubes-doc>`__ must pass review prior to be merged, except in the case of :ref:`external documentation <external-documentation>` (see `#4693 <https://github.com/QubesOS/qubes-issues/issues/4693>`__). This process is designed to ensure that contributed text is accurate and non-malicious. This process is a best effort that should provide a reasonable degree of assurance, but it is not foolproof. For example, all text characters are checked for ANSI escape sequences. However, binaries, such as images, are simply checked to ensure they appear or function the way they should when the website is rendered. They are not further analyzed in an attempt to determine whether they are malicious.
+All pull requests (PRs) against `qubesos.github.io <https://github.com/QubesOS/qubesos.github.io>`__ must pass review prior to be merged. This process is designed to ensure that contributed text is accurate and non-malicious. This process is a best effort that should provide a reasonable degree of assurance, but it is not foolproof. For example, all text characters are checked for ANSI escape sequences. However, binaries, such as images, are simply checked to ensure they appear or function the way they should when the website is rendered. They are not further analyzed in an attempt to determine whether they are malicious.
 
-Once a pull request passes review, the reviewer should add a signed comment stating, “Passed review as of ``<LATEST_COMMIT>``” (or similar). The documentation maintainer then verifies that the pull request is mechanically sound (no merge conflicts, broken links, ANSI escapes, etc.). If so, the documentation maintainer then merges the pull request, adds a PGP-signed tag to the latest commit (usually the merge commit), then pushes to the remote. In cases in which another reviewer is not required, the documentation maintainer may review the pull request (in which case no signed comment is necessary, since it would be redundant with the signed tag).
+Once a pull request passes review, the reviewer should add a signed comment stating, "Passed review as of ``<LATEST_COMMIT>``" (or similar). The website maintainer then verifies that the pull request is mechanically sound (no merge conflicts, broken links, ANSI escapes, etc.). If so, the website maintainer then merges the pull request, adds a PGP-signed tag to the latest commit (usually the merge commit), then pushes to the remote. In cases in which another reviewer is not required, the website maintainer may review the pull request (in which case no signed comment is necessary, since it would be redundant with the signed tag).
 
 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 documentation or about how to edit the documentation, 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 documentation should be fixed or improved, please `contribute <#how-to-submit-a-pull-request>`__ the change yourself. To report an issue with the documentation, please follow our standard :doc:`issue reporting guidelines </introduction/issue-tracking>`. (If you report an issue with the documentation, 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.)
-
-.. |page-source-button| image:: /attachment/doc/doc-pr_01_page-source-button.png
-   
-
-.. |github-edit| image:: /attachment/doc/doc-pr_02_github-edit.png
-   
-
-.. |github-sign-in| image:: /attachment/doc/doc-pr_03_sign-in.png
-   
-
-.. |fork| image:: /attachment/doc/doc-pr_04_fork.png
-   
-
-.. |edit| image:: /attachment/doc/doc-pr_05_edit.png
-   
-
-.. |commit| image:: /attachment/doc/doc-pr_06_commit-msg.png
-   
-
-.. |pull-request| image:: /attachment/doc/doc-pr_07_review-changes.png
-   
-
-.. |pull-request-confirm| image:: /attachment/doc/doc-pr_08_create-pull-request.png
-   
-
-.. |done| image:: /attachment/doc/doc-pr_09_done.png
-   
+.. |news-section| image:: /attachment/doc/website_news_section.png
+.. |hcl-section| image:: /attachment/doc/website_hcl.png

developer/general/markdown-style-guide.rst

@@ -1,428 +0,0 @@
-====================
-Markdown style guide
-====================
-
-
-*Also see* :doc:`how to edit the documentation </developer/general/how-to-edit-the-documentation>` *.*
-
-Qubes OS documentation pages are stored as plain text Markdown files in the `qubes-doc <https://github.com/QubesOS/qubes-doc>`__ repository. By cloning and regularly pulling from this repo, users can maintain their own up-to-date offline copy of all Qubes documentation rather than relying solely on the web.
-
-The documentation is a volunteer community effort. People like you are constantly working to make it better. If you notice something that can be fixed or improved, please :doc:`edit the documentation </developer/general/how-to-edit-the-documentation>`!
-
-This page explains the standards we follow for writing, formatting, and organizing the documentation. Please follow these guidelines and conventions when editing the documentation. For the standards governing the website as a whole, please see the :doc:`website style guide </developer/general/website-style-guide>`.
-
-Markdown conventions
---------------------
-
-
-All the documentation is written in Markdown for maximum accessibility. When making contributions, please observe the following style conventions. If you’re not familiar with Markdown syntax, `this <https://daringfireball.net/projects/markdown/>`__ is a great resource.
-
-Hyperlink syntax
-^^^^^^^^^^^^^^^^
-
-
-Use non-reference-style links like `` `website <https://example.com/>`__``. Do *not* use reference-style links like ``[website][example]``, ``[website][]`` or ``[website]``. This facilitates the localization process.
-
-Relative vs. absolute links
-^^^^^^^^^^^^^^^^^^^^^^^^^^^
-
-
-Always use relative rather than absolute paths for internal website links. For example, use ``/doc/documentation-style-guide/`` instead of ``https://www.qubes-os.org/doc/documentation-style-guide/``.
-
-You may use absolute URLs in the following cases:
-
-- External links
-
-- URLs that appear inside code blocks (e.g., in comments and document templates, and the plain text reproductions of `QSBs <https://www.qubes-os.org/security/qsb/>`__ and `Canaries <https://www.qubes-os.org/security/canary/>`__), since they’re not hyperlinks
-
-- Git repo files like ``README.md`` and ``CONTRIBUTING.md``, since they’re not part of the website itself but rather of the auxiliary infrastructure supporting the website
-
-
-
-This rule is important because using absolute URLs for internal website links breaks:
-
-- Serving the website offline
-
-- Website localization
-
-- Generating offline documentation
-
-- Automatically redirecting Tor Browser visitors to the correct page on the onion service mirror
-
-
-
-Image linking
-^^^^^^^^^^^^^
-
-
-See :ref:`how to add images <developer/general/how-to-edit-the-documentation:how to add images>` for the required syntax. This will make the image a hyperlink to the image file, allowing the reader to click on the image in order to view the full image by itself. This is important. Following best practices, our website has a responsive design, which allows the website to render appropriately across all screen sizes. When viewing this page on a smaller screen, such as on a mobile device, the image will automatically shrink down to fit the screen. If visitors cannot click on the image to view it in full size, then, depending on their device, they may have no way see the details in the image clearly.
-
-In addition, make sure to link only to images in the `qubes-attachment <https://github.com/QubesOS/qubes-attachment>`__ repository. Do not attempt to link to images hosted on other websites.
-
-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.
-
-Headings
-^^^^^^^^
-
-
-Do not use ``h1`` headings (single ``#`` or ``======`` underline). These are automatically generated from the ``title:`` line in the YAML front matter.
-
-Use Atx-style syntax for headings: ``##h2``, ``### h3``, etc. Do not use underlining syntax (``-----``).
-
-Indentation
-^^^^^^^^^^^
-
-
-Use spaces instead of tabs. Use hanging indentations where appropriate.
-
-Lists
-^^^^^
-
-
-If appropriate, make numerals in numbered lists match between Markdown source and HTML output. Some users read the Markdown source directly, and this makes numbered lists easier to follow.
-
-Code blocks
-^^^^^^^^^^^
-
-
-When writing code blocks, use `syntax highlighting <https://github.github.com/gfm/#info-string>`__ where possible (see `here <https://github.com/jneen/rouge/wiki/List-of-supported-languages-and-lexers>`__ for a list of supported languages). Use ``[...]`` for anything omitted.
-
-Line wrapping
-^^^^^^^^^^^^^
-
-
-Do not hard wrap text, except where necessary (e.g., inside code blocks).
-
-Do not use Markdown syntax for styling
-^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
-
-
-For example, there is a common temptation to use block quotations (created by beginning lines with the ``>`` character) in order to stylistically distinguish some portion of text from the rest of the document, e.g.:
-
-.. code:: bash
-
-      > **Note:** This is an important note!
-
-
-
-This renders as:
-
-   **Note:** This is an important note!
-
-There are two problems with this:
-
-1. It is a violation of the `separation of content and presentation <https://en.wikipedia.org/wiki/Separation_of_content_and_presentation>`__, since it abuses markup syntax in order to achieve unintended stylistic results. The Markdown (and HTML, if any) should embody the *content* of the documentation, while the *presentation* is handled by (S)CSS.
-
-2. It is an abuse of quotation syntax for text that is not actually a quotation. (You are not quoting anyone here. You’re just telling the reader to note something and trying to draw their attention to your note visually.)
-
-
-
-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.,:
-
-.. code:: bash
-
-      **Note:** This is an important note.
-
-
-
-This renders as:
-
-**Note:** This is an important note.
-
-Alerts
-^^^^^^
-
-
-Alerts are sections of HTML used to draw the reader’s attention to important information, such as warnings, and for stylistic purposes. They are typically styled as colored text boxes, usually accompanied by icons. Alerts should generally be used somewhat sparingly, so as not to cause `alert fatigue <https://en.wikipedia.org/wiki/Alarm_fatigue>`__ and since they must be written in HTML instead of Markdown, which makes the source less readable and more difficult to work with for localization and automation purposes. Here are examples of several types of alerts and their recommended icons:
-
-.. code:: bash
-
-      <div class="alert alert-success" role="alert">
-        <i class="fa fa-check-circle"></i>
-        <b>Did you know?</b> The Qubes OS installer is completely offline. It doesn't
-        even load any networking drivers, so there is no possibility of
-        internet-based data leaks or attacks during the installation process.
-      </div>
-      
-      <div class="alert alert-info" role="alert">
-        <i class="fa fa-info-circle"></i>
-        <b>Note:</b> Using Rufus to create the installation medium means that you <a
-        href="https://github.com/QubesOS/qubes-issues/issues/2051">won't be able</a>
-        to choose the "Test this media and install Qubes OS" option mentioned in the
-        example below. Instead, choose the "Install Qubes OS" option.
-      </div>
-      
-      <div class="alert alert-warning" role="alert">
-        <i class="fa fa-exclamation-circle"></i>
-        <b>Note:</b> Qubes OS is not meant to be installed inside a virtual machine
-        as a guest hypervisor. In other words, <b>nested virtualization</b> is not
-        supported. In order for a strict compartmentalization to be enforced, Qubes
-        OS needs to be able to manage the hardware directly.
-      </div>
-      
-      <div class="alert alert-danger" role="alert">
-        <i class="fa fa-exclamation-triangle"></i>
-        <b>Warning:</b> Qubes has no control over what happens on your computer
-        before you install it. No software can provide security if it is installed on
-        compromised hardware. Do not install Qubes on a computer you don't trust. See
-        [installation security](/doc/install-security/) for more
-        information.
-      </div>
-
-
-
-These render as:
-
-.. note::
-      
-      **Did you know?** The Qubes OS installer is completely offline. It doesn’t even load any networking drivers, so there is no possibility of internet-based data leaks or attacks during the installation process.
-
-.. note::
-      
-      **Note:** Using Rufus to create the installation medium means that you won’t be able to choose the “Test this media and install Qubes OS” option mentioned in the example below. Instead, choose the “Install Qubes OS” option.
-
-.. warning::
-      
-      **Note:** Qubes OS is not meant to be installed inside a virtual machine as a guest hypervisor. In other words, *nested virtualization* is not supported. In order for a strict compartmentalization to be enforced, Qubes OS needs to be able to manage the hardware directly.
-
-.. DANGER::
-      
-      **Warning:** Qubes has no control over what happens on your computer before you install it. No software can provide security if it is installed on compromised hardware. Do not install Qubes on a computer you don’t trust. See :doc:`installation security </user/downloading-installing-upgrading/install-security>`       for more information.
-
-Writing guidelines
-------------------
-
-
-Correct use of terminology
-^^^^^^^^^^^^^^^^^^^^^^^^^^
-
-
-Familiarize yourself with the terms defined in the :doc:`glossary </user/reference/glossary>`. Use these terms consistently and accurately throughout your writing.
-
-Sentence case in headings
-^^^^^^^^^^^^^^^^^^^^^^^^^
-
-
-Use sentence case (rather than title case) in headings for the reasons explained `here <https://www.sallybagshaw.com.au/articles/sentence-case-v-title-case/>`__. In particular, since the authorship of the Qubes documentation is decentralized and widely distributed among users from around the world, many contributors come from regions with different conventions for implementing title case, not to mention that there are often differing style guide recommendations even within a single region. It is much easier for all of us to implement sentence case consistently across our growing body of pages, which is very important for managing the ongoing maintenance burden and sustainability of the documentation.
-
-Writing command-line examples
-^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
-
-
-When providing command-line examples:
-
-- Tell the reader where to open a terminal (dom0 or a specific domU), and show the command along with its output (if any) in a code block, e.g.:
-
-  .. code:: bash
-
-        Open a terminal in dom0 and run:
-        ```
-        $ cd test
-        $ echo Hello
-        Hello
-        ```
-
-
-- Precede each command with the appropriate command prompt: At a minimum, the prompt should contain a trailing ``#`` (for the user ``root``) or ``$`` (for other users) on Linux systems and ``>`` on Windows systems, respectively.
-
-- Don’t try to add comments inside the code block. For example, *don’t* do this:
-
-  .. code:: bash
-
-        Open a terminal in dom0 and run:
-        ```
-        # Navigate to the new directory
-        $ cd test
-        # Generate a greeting
-        $ echo Hello
-        Hello
-        ```
-
-  The ``#`` symbol preceding each comment is ambiguous with a root command prompt. Instead, put your comments *outside* of the code block in normal prose.
-
-
-
-Variable names in commands
-^^^^^^^^^^^^^^^^^^^^^^^^^^
-
-
-Syntactically distinguish variables in commands. For example, this is ambiguous:
-
-.. code:: bash
-
-      $ qvm-run --dispvm=disposable-template --service qubes.StartApp+xterm
-
-
-
-It should instead be:
-
-.. code:: bash
-
-      $ qvm-run --dispvm=<DISPOSABLE_TEMPLATE> --service qubes.StartApp+xterm
-
-
-
-Note that we syntactically distinguish variables in three ways:
-
-1. Surrounding them in angled brackets (``< >``)
-
-2. Using underscores (``_``) instead of spaces between words
-
-3. Using all capital letters
-
-
-
-We have observed that many novices make the mistake of typing the surrounding angled brackets (``< >``) on the command line, even after substituting the desired real value between them. Therefore, in documentation aimed at novices, we also recommend clarifying that the angled brackets should not be typed. This can be accomplished in one of several ways:
-
-- Explicitly say something like “without the angled brackets.”
-
-- Provide an example command using real values that excludes the angled brackets.
-
-- If you know that almost all users will want to use (or should use) a specific command containing all real values and no variables, you might consider providing exactly that command and forgoing the version with variables. Novices may not realize which parts of the command they can substitute with different values, but if you’ve correctly judged that they should use the command you’ve provided as is, then this shouldn’t matter.
-
-
-
-Capitalization of "qube"
-^^^^^^^^^^^^^^^^^^^^^^^^
-
-
-We introduced the term :ref:`“qube” <user/reference/glossary:qube>` as a user-friendly alternative to the term :ref:`“virtual machine” (“VM”) <user/reference/glossary:vm>` in the context of Qubes OS. Nonetheless, “qube” is a common noun like the words “compartment” and “container.” Therefore, in English, “qube” follows the standard capitalization rules for common nouns. For example, “I have three qubes” is correct, while “I have three Qubes” is incorrect. Like other common nouns, “qube” should still be capitalized at the beginnings of sentences, the beginnings of sentence-case headings, and in title-case headings. Note, however, that starting a sentence with the plural of “qube” (e.g., “Qubes can be shut down…”) can be ambiguous, since it may not be clear whether the referent is a plurality of qubes, :ref:`Qubes OS <user/reference/glossary:qubes os>`, or even the Qubes OS Project itself. Hence, it is generally a good idea to rephrase such sentences in order to avoid this ambiguity.
-
-Many people feel a strong temptation to capitalize the word “qube” all the time, like a proper noun, perhaps because it’s a new and unfamiliar term that’s closely associated with a particular piece of software (namely, Qubes OS). However, these factors are not relevant to the capitalization rules of English. In fact, it’s not unusual for new common nouns to be introduced into English, especially in the context of technology. For example, “blockchain” is a relatively recent technical term that’s a common noun. Why is it a common noun rather than a proper noun? Because proper nouns refer to *particular* people, places, things, and ideas. There are many different blockchains. However, even when there was just one, the word still denoted a collection of things rather than a particular thing. It happened to be the case that there was only one member in that collection at the time. For example, if there happened to be only one tree in the world, that wouldn’t change the way we capitalize sentences like, “John sat under a tree.” Intuitively, it makes sense that the addition and removal of objects from the world shouldn’t cause published books to become orthographicallly incorrect while sitting on their shelves.
-
-Accordingly, the reason “qube” is a common noun rather than a proper noun is because it doesn’t refer to any one specific thing (in this case, any one specific virtual machine). Rather, it’s the term for any virtual machine in a Qubes OS installation. (Technically, while qubes are currently implemented as virtual machines, Qubes OS is independent of its underlying compartmentalization technology. Virtual machines could be replaced with a different technology, and qubes would still be called “qubes.”)
-
-I have several qubes in my Qubes OS installation, and you have several in yours. Every Qubes OS user has their own set of qubes, just as each of us lives in some neighborhood on some street. Yet we aren’t tempted to treat words like “neighborhood” or “street” as proper nouns (unless, of course, they’re part of a name, like “Acorn Street”). Again, while this might seem odd because “qube” is a new word that we invented, that doesn’t change how English works. After all, *every* word was a new word that someone invented at some point (otherwise we wouldn’t have any words at all). We treat “telephone,” “computer,” “network,” “program,” and so on as common nouns, even though those were all new technological inventions in the not-too-distant past (on a historical scale, at least). So, we shouldn’t allow ourselves to be confused by irrelevant factors, like the fact that the inventors happened to be *us* or that the invention was *recent* or is not in widespread use among humanity.
-
-English language conventions
-^^^^^^^^^^^^^^^^^^^^^^^^^^^^
-
-
-For the sake of consistency and uniformity, the Qubes documentation aims to follow the conventions of American English, where applicable. (Please note that this is an arbitrary convention for the sake consistency and not a value judgment about the relative merits of British versus American English.)
-
-Organizational guidelines
--------------------------
-
-
-Do not duplicate documentation
-^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
-
-
-Duplicating documentation is almost always a bad idea. There are many reasons for this. The main one is that almost all documentation has to be updated as some point. When similar documentation appears in more than one place, it is very easy for it to get updated in one place but not the others (perhaps because the person updating it doesn’t realize it’s in more than once place). When this happens, the documentation as a whole is now inconsistent, and the outdated documentation becomes a trap, especially for novice users. Such traps are often more harmful than if the documentation never existed in the first place. The solution is to **link** to existing documentation rather than duplicating it. There are some exceptions to this policy (e.g., information that is certain not to change for a very long time), but they are rare.
-
-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-documentation:how to edit the documentation index>`) to add and update Qubes Forum links in the :ref:`“External documentation” <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.
-
-Many contributors do not realize that there is a significant amount of work involved in *maintaining* documentation after it has been written. They may wish to write documentation and submit it to the core docs, but they see only their own writing process and fail to consider that it will have to be kept up-to-date and consistent with the rest of the docs for years afterward. Submissions to the core docs also have to :ref:`undergo a review process <developer/general/how-to-edit-the-documentation:security>` to ensure accuracy before being merged, which takes up valuable time from the team. We aim to maintain high quality standards for the core docs (style and mechanics, formatting), which also takes up a lot of time. If the documentation involves anything external to the Qubes OS Project (such as a website, platform, program, protocol, framework, practice, or even a reference to a version number), the documentation is likely to become outdated when that external thing changes. It’s also important to periodically review and update this documentation, especially when a new Qubes release comes out. Periodically, there may be technical or policy changes that affect all the core documentation. The more documentation there is relative to maintainers, the harder all of this will be. Since there are many more people who are willing to write documentation than to maintain it, these individually small incremental additions amount to a significant maintenance burden for the project.
-
-On the positive side, we consider the existence of community documentation to be a sign of a healthy ecosystem, and this is quite common in the software world. The community is better positioned to write and maintain documentation that applies, combines, and simplifies the official documentation, e.g., tutorials that explain how to install and use various programs in Qubes, how to create custom VM setups, and introductory tutorials that teach basic Linux concepts and commands in the context of Qubes. In addition, just because the Qubes OS Project has officially written and maintains some flexible framework, such as ``qrexec``, it does not make sense to include every tutorial that says “here’s how to do something cool with ``qrexec``” in the core docs. Such tutorials generally also belong in the community documentation.
-
-See `#4693 <https://github.com/QubesOS/qubes-issues/issues/4693>`__ for more background information.
-
-Release-specific documentation
-^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
-
-
-*See* `#5308 <https://github.com/QubesOS/qubes-issues/issues/5308>`__ *for pending changes to this policy.*
-
-We maintain only one set of documentation for Qubes OS. We do not maintain a different set of documentation for each release of Qubes. Our single set of Qubes OS documentation is updated on a continual, rolling basis. Our first priority is to document all **current, stable releases** of Qubes. Our second priority is to document the next, upcoming release (if any) that is currently in the beta or release candidate stage.
-
-In cases where a documentation page covers functionality that differs considerably between Qubes OS releases, the page should be subdivided into clearly-labeled sections that cover the different functionality in different releases (examples below).
-
-In general, avoid mentioning specific Qubes versions in the body text of documentation, as these references rapidly go out of date and become misleading to readers.
-
-Incorrect Example
-^^^^^^^^^^^^^^^^^
-
-
-.. code:: bash
-
-      ## How to Foo
-      
-      Fooing is the process by which one foos. There are both general and specific
-      versions of fooing, which vary in usefulness depending on your goals, but for
-      the most part, all fooing is fooing.
-      
-      To foo in Qubes 3.2:
-      
-         $ qvm-foo <foo-bar>
-      
-      Note that this does not work in Qubes 4.0, where there is a special widget
-      for fooing, which you can find in the lower-right corner of the screen in
-      the Foo Manager. Alternatively, you can use the more general `qubes-baz`
-      command introduced in 4.0:
-      
-         $ qubes-baz --foo <bar>
-      
-      Once you foo, make sure to close the baz before fooing the next bar.
-
-
-
-Correct Example
-^^^^^^^^^^^^^^^
-
-
-.. code:: bash
-
-      ## Qubes 3.2
-      
-      ### How to Foo
-      
-      Fooing is the process by which one foos. There are both general and specific
-      versions of fooing, which vary in usefulness depending on your goals, but for
-      the most part, all fooing is fooing.
-      
-      To foo:
-      
-         $ qvm-foo <foo-bar>
-      
-      Once you foo, make sure to close the baz before fooing the next bar.
-      
-      ## Qubes 4.0
-      
-      ### How to Foo
-      
-      Fooing is the process by which one foos. There are both general and specific
-      versions of fooing, which vary in usefulness depending on your goals, but for
-      the most part, all fooing is fooing.
-      
-      There is a special widget for fooing, which you can find in the lower-right
-      corner of the screen in the Foo Manager. Alternatively, you can use the
-      general `qubes-baz` command:
-      
-         $ qubes-baz --foo <bar>
-      
-      Once you foo, make sure to close the baz before fooing the next bar.
-
-
-
-Subdividing the page into clearly-labeled sections for each release has several benefits:
-
-- It preserves good content for older (but still supported) releases. Many documentation contributors are also people who prefer to use the latest release. Many of them are tempted to *replace* existing content that applies to an older, supported release with content that applies only to the latest release. This is somewhat understandable. Since they only use the latest release, they may be focused on their own experience, and they may even regard the older release as deprecated, even when it’s actually still supported. However, allowing this replacement of content would do a great disservice to those who still rely on the older, supported release. In many cases, these users value the stability and reliability of the older, supported release. With the older, supported release, there has been more time to fix bugs and make improvements in both the software and the documentation. Consequently, much of the documentation content for this release may have gone through several rounds of editing, review, and revision. It would be a tragedy for this content to vanish while the very set of users who most prize stability and reliability are depending on it.
-
-- It’s easy for readers to quickly find the information they’re looking for, since they can go directly to the section that applies to their release.
-
-- It’s hard for readers to miss information they need, since it’s all in one place. In the incorrect example, information that the reader needs could be in any paragraph in the entire document, and there’s no way to tell without reading the entire page. In the correct example, the reader can simply skim the headings in order to know which parts of the page need to be read and which can be safely ignored. The fact that some content is repeated in the two release-specific sections is not a problem, since no reader has to read the same thing twice. Moreover, as one release gets updated, it’s likely that the documentation for that release will also be updated. Therefore, content that is initially duplicated between release-specific sections will not necessarily stay that way, and this is a good thing: We want the documentation for a release that *doesn’t* change to stay the same, and we want the documentation for a release that *does* change to change along with the software.
-
-- It’s easy for documentation contributors and maintainers to know which file to edit and update, since there’s only one page for all Qubes OS releases. Initially creating the new headings and duplicating content that applies to both is only a one-time cost for each page, and many pages don’t even require this treatment, since they apply to all currently-supported Qubes OS releases.
-
-
-
-By contrast, an alternative approach, such as segregating the documentation into two different branches, would mean that contributions that apply to both Qubes releases would only end up in one branch, unless someone remembered to manually submit the same thing to the other branch and actually made the effort to do so. Most of the time, this wouldn’t happen. When it did, it would mean a second pull request that would have to be reviewed. Over time, the different branches would diverge in non-release-specific content. Good general content that was submitted only to one branch would effectively disappear once that release was deprecated. (Even if it were still on the website, no one would look at it, since it would explicitly be in the subdirectory of a deprecated release, and there would be a motivation to remove it from the website so that search results wouldn’t be populated with out-of-date information.)
-
-For further discussion about release-specific documentation in Qubes, see `here <https://groups.google.com/d/topic/qubes-users/H9BZX4K9Ptk/discussion>`__.
-
-Git conventions
----------------
-
-
-Please follow our :ref:`Git commit message guidelines <developer/code/coding-style:commit message guidelines>`.

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

@@ -2,33 +2,19 @@
 reStructuredText documentation style guide
 ===========================================
 
-*Also see* :doc:`How to edit the documentation </developer/general/how-to-edit-the-rst-documentation/>` *.*
-
-Qubes OS documentation is stored as reStrucutredText files in the `qubes-doc <https://github.com/QubesOS/qubes-doc>`__ repository.
-By cloning and regularly pulling from this repo, users can maintain their own up-to-date offline copy of all Qubes documentation
-rather than relying solely on the web. Additionally one can download a EPUB or PDF version of the documentation from `doc.qubes-os.org <https://doc.qubes-os.org/en/latest/>`__.
-
-We use `Sphinx <https://www.sphinx-doc.org/>`__ for building and
-`Read The Docs <https://readsthedocs.com/>`__ for hosting.
-
-.. figure::/attachment/doc/rst-rtd-workflow.png
-    :alt: Qubes OS Documentation Workflow
-
-The documentation is a volunteer community effort. People like you are constantly working to make it better.
-If you notice something that can be fixed or improved,
-please :doc:`edit the documentation </developer/general/how-to-edit-the-rst-documentation/>`!
+*Also see* :doc:`How to edit the documentation </developer/general/how-to-edit-the-rst-documentation/>`.
 
 This page explains the standards we follow for writing, formatting, and organizing the documentation.
 Please follow these guidelines and conventions when editing the rST documentation.
-For the standards governing the website (as opposed to the rST documentation hosted on RTD),
-please see the `website style guide <https://www.qubes-os.org/doc/website-style-guide/>`__.
-If you wish to submit a PR regarding markdown content hosted on the website, please refer to
-`how to edit the Markdown pages <https://www.qubes-os.org/doc/doc/how-to-edit-the-website/>`__.
+For the standards governing the website (as opposed to the rST documentation hosted on `https://doc.qubes-os.org <https://doc.qubes-os.org>`__),
+please see the :doc:`website style guide </developer/general/website-style-guide>`.
+If you wish to submit a pull request regarding content hosted on the website, please refer to
+:doc:`How to edit the website </developer/general/how-to-edit-the-website/>`.
 
 reStructuredText conventions
 ----------------------------
 
-All the documentation is written in reStructuredText. When making contributions, please observe the following style conventions.
+All the documentation is written in `reStructuredText (rST) <https://docutils.sourceforge.io/rst.html>`__. When making contributions, please observe the following style conventions.
 If you’re not familiar with reStructuredText syntax, `the Sphinx primer <https://www.sphinx-doc.org/en/master/usage/restructuredtext/basics.html>`__
 is a great resource, as well as `this quick reStructuredText <https://docutils.sourceforge.io/docs/user/rst/quickref.html>`__.
 Please always be mindful that rST syntax is sensitive to indentation!
@@ -39,23 +25,250 @@ Directives
 
 A `directive <https://www.sphinx-doc.org/en/master/usage/restructuredtext/directives.html>`__ is a generic block of explicit markup,
 provided by `Docutils <https://www.docutils.org/>`__ and extended by `Sphinx <https://www.sphinx-doc.org/>`__.
-
 Directives are used to insert non-paragraph content, such as images, tables, and code blocks.
-
 Example directives are:
 
-.. code-block :: rst
+.. code-block:: rst
 
-   .. image::, .. code-block::, etc.
+   .. image::
+   .. code-block::
+   .. figure::
 
 Directives start with ``..``, followed by directive name, arguments, options, and indented content.
 
+Images
+""""""
+
+To include images (without a caption), use the ``image`` directive.
+You need to specify the path to the image and an alt text.
+
+.. code-block:: rst
+
+  .. image:: path/to/image.png
+     :alt: Alternative text
+     :width: 200px
+     :align: center
+
+Read The Docs and the HTML `sphinx-rtd-theme <https://sphinx-rtd-theme.readthedocs.io/en/stable/>`__ in use
+have a responsive design, which allows the documentation to render appropriately across all screen sizes.
+
+Make sure to link only to images in the :file:`attachment/doc` folder of the `qubes-doc <https://github.com/QubesOS/qubes-doc>`__ repository.
+Do not attempt to link to images hosted on other websites.
+
+See also :ref:`how_to_add_images` for the further information and about using the ``figure`` directive.
+
+Lists
+"""""
+
+`Lists <https://www.sphinx-doc.org/en/master/usage/restructuredtext/basics.html#lists-and-quote-like-blocks>`__ can be bullet lists (\*, +, -), enumerated lists (1., 2., etc.), definition lists, field lists.
+
+Nested lists must be separated from the parent list items by blank lines:
+
+.. code-block:: rst
+
+  - Item 1
+  - Item 2
+
+    - Subitem 2.1
+    - Subitem 2.2
+
+  - Item 3
+
+Numbered lists can be autonumbered using the ``#`` sign.
+
+.. code-block:: rst
+
+  #. Item 1
+  #. Item 2
+
+    #. Subitem 2.1
+    #. Subitem 2.2
+
+  #. Item 3
+
+Item 3 will start at 1.
+
+Code blocks
+"""""""""""
+
+When writing code blocks, use syntax highlighting within the `code-block <https://www.sphinx-doc.org/en/master/usage/restructuredtext/directives.html#directive-code-block>`__
+or `code <https://www.sphinx-doc.org/en/master/usage/restructuredtext/directives.html#directive-code>`__.
+
+By specifying the language, you enable pygments, which show syntax color coding for that code sample (see `here <https://pygments.org/languages/>`__ for a list of supported languages).
+
+.. code-block:: rst
+
+   .. code-block:: language
+
+     code
+
+
+
+Use ``[...]`` for anything omitted.
+
+For inlining small code snippets you can use the `code role <https://www.sphinx-doc.org/en/master/usage/restructuredtext/roles.html#role-code>`__ as in
+
+.. code-block:: rst
+
+   `code:`:term:`qube``
+
+You can add line numbers to code examples with the ``:linenos:`` parameter.
+
+.. code-block:: rst
+
+    .. code-block:: python
+      :linenos:
+
+       def hello_world():
+         print("Hello, world!")
+
+
+You can have certain lines with the ``:emphasize-lines:`` parameter.
+
+.. code-block:: rst
+
+ .. code-block:: python
+   :emphasize-lines: 1,3,4
+
+
+
+For Python use ``python``.
+
+.. code-block:: rst
+
+    .. code-block:: python
+
+      string_var = 'python'
+
+For Bash use ``bash``.
+
+.. code-block:: rst
+
+    .. code-block:: bash
+
+      echo "Hello"
+
+For a terminal session use ``console``.
+
+.. code-block:: rst
+
+    .. code-block:: console
+
+      pygments_style = 'sphinx'
+
+For text output use ``output``.
+
+.. code-block:: rst
+
+    .. code-block:: output
+
+       some output
+
+For text use ``text``.
+
+.. code-block:: rst
+
+    .. code-block:: text
+
+       some text
+
+
+Tables
+""""""
+
+We adhere to the list tables directive by docutils as described `here <https://docutils.sourceforge.io/docs/ref/rst/directives.html#list-table-1>`__.
+
+A simple example would be:
+
+    .. code-block:: rst
+
+        .. list-table:: rst
+           :widths: 15 10
+           :header-rows: 1
+
+           * - Header 1
+             - Header 2
+           * - Cell 1
+             - Cell 2
+           * - Cell 3
+             - Cell 4
+
+Admonitions, messages, and warnings
+"""""""""""""""""""""""""""""""""""
+
+`Admonitions, messages, and warnings <https://www.sphinx-doc.org/en/master/usage/restructuredtext/directives.html#admonitions-messages-and-warnings>`__ are used to draw the reader’s attention to important information, such as warnings, and for stylistic purposes.
+They are typically styled as colored text boxes, usually accompanied by icons provided out of the box by Sphinx and rST.
+Alerts should generally be used somewhat sparingly, so as not to cause `alert fatigue <https://en.wikipedia.org/wiki/Alarm_fatigue>`__.
+
+Here are examples of several types of alerts:
+
+.. code:: rst
+
+    .. hint::
+       **Did you know?** The Qubes OS installer is completely offline. It doesn't
+       even load any networking drivers, so there is no possibility of
+       internet-based data leaks or attacks during the installation process.
+
+     .. note::
+       **Note:*</b>** Using Rufus to create the installation medium means that you
+       `wont be able <https://github.com/QubesOS/qubes-issues/issues/2051">`__
+       to choose the "Test this media and install Qubes OS" option mentioned in the
+       example below. Instead, choose the "Install Qubes OS" option.
+
+     .. warning::
+       **Note:** Qubes OS is not meant to be installed inside a virtual machine
+       as a guest hypervisor. In other words, **nested virtualization** is not
+       supported. In order for a strict compartmentalization to be enforced, Qubes
+       OS needs to be able to manage the hardware directly.
+
+     .. danger::
+       **Warning:** Qubes has no control over what happens on your computer
+       before you install it. No software can provide security if it is installed on
+       compromised hardware. Do not install Qubes on a computer you don't trust. See
+       installation security for more information.
+
+
+
+These render as:
+
+.. hint::
+       **Did you know?** The Qubes OS installer is completely offline. It doesn't
+       even load any networking drivers, so there is no possibility of
+       internet-based data leaks or attacks during the installation process.
+
+.. note::
+       **Note:** Using Rufus to create the installation medium means that you
+       `won't be able <"https://github.com/QubesOS/qubes-issues/issues/2051">`__
+       to choose the "Test this media and install Qubes OS" option mentioned in the
+       example below. Instead, choose the "Install Qubes OS" option.
+
+.. warning::
+       **Note:** Qubes OS is not meant to be installed inside a virtual machine
+       as a guest hypervisor. In other words, **nested virtualization** is not
+       supported. In order for a strict compartmentalization to be enforced, Qubes
+       OS needs to be able to manage the hardware directly.
+
+.. danger::
+       **Warning:** Qubes has no control over what happens on your computer
+       before you install it. No software can provide security if it is installed on
+       compromised hardware. Do not install Qubes on a computer you don't trust. See
+       installation security for more information.
+
+
+Glossary
+""""""""
+
+The Sphinx `glossary directive <https://www.sphinx-doc.org/en/master/usage/restructuredtext/directives.html#glossary>`__
+is created with a simple ``.. glossary::`` block in :file:`/user/reference/glossary.rst`.
+Anywhere else in the documentation you can link to a term using the role: :code:`:term:`qube``
+which automatically generates a hyperlink to the glossary entry :term:`qube`.
 
 
 Roles
 ^^^^^
 
-Sphinx uses interpreted text `roles <https://www.sphinx-doc.org/en/master/usage/restructuredtext/roles.html>`__ to insert semantic markup into documents.
+Sphinx uses interpreted text `roles <https://www.sphinx-doc.org/en/master/usage/restructuredtext/roles.html>`__ to insert semantic markup into documents
+and thus enhance the readability and consistency of the documentation.
 
 Syntax is as follows:
 
@@ -65,10 +278,17 @@ Syntax is as follows:
 
 In Qubes OS documentation the `doc <https://www.sphinx-doc.org/en/master/usage/referencing.html#role-doc>`__ and
 `ref <https://www.sphinx-doc.org/en/master/usage/referencing.html#role-ref>`__ roles are used extensively
-as described :ref:`here <developer/general/how-to-edit-the-rst-documentation:cross-referencing>`.
+as described in :ref:`cross_referencing`.
 
+The roles used in the Qubes OS documentation so far are:
+
+- the ``:file:`` `role <https://www.sphinx-doc.org/en/master/usage/restructuredtext/roles.html#role-file>`__
+- the ``:guilabel:`` `role <https://www.sphinx-doc.org/en/master/usage/restructuredtext/roles.html#role-guilabel>`__
+- the ``:menuselection:`` `role <https://www.sphinx-doc.org/en/master/usage/restructuredtext/roles.html#role-menuselection>`__
+- the ``:samp:`` `role <https://www.sphinx-doc.org/en/master/usage/restructuredtext/roles.html#role-samp>`__
+
+Please continue using the above or new ones where appropriate.
 
-TODO Blocks: Literal blocks, code blocks, block quotes, code blocks (with syntax highlighting), doctest blocks, footnotes, citations, tables (simple and complex), admonitions (note, warning, danger).
 
 
 Cross referencing:
@@ -87,6 +307,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>`.
 
 
@@ -127,7 +348,7 @@ instead of:
 
 .. code-block:: rst
 
-  text `contribute code <https://https://doc.qubes-os.org/en/latest/introduction/contributing.html>`__ text
+  text :doc:`contribute code </introduction/contributing>` text
 
 You may use absolute URLs in the following cases:
 
@@ -144,31 +365,6 @@ This rule is important because using absolute URLs for internal website links br
 - Generating offline documentation
 
 
-Image linking
-^^^^^^^^^^^^^
-
-
-See :ref:`how to add images <developer/general/how-to-edit-the-documentation:how to add images>` for the required syntax.
-Read The Docs and the used RTD theme have a responsive design, which allows the documentation to render appropriately across all screen sizes.
-When viewing this page on a smaller screen, such as on a mobile device, the image will automatically shrink down to fit the screen.
-If visitors cannot click on the image to view it in full size, then, depending on their device, they may have no way see the details in the image clearly.
-
-In addition, make sure to link only to images in the `attachment/doc` folder of the `qubes-doc <https://github.com/QubesOS/qubes-doc>`__ repository.
-Do not attempt to link to images hosted on other websites.
-
-
-To include images without a caption, use the ``image`` directive. You need to specify the path to the image and an optional alt text.
-
-.. code-block:: rst
-
-  .. image:: path/to/image.png
-     :alt: Alternative text
-     :width: 200px
-     :align: center
-
-To using the ``figure`` directive please read :ref:`how to add images <developer/general/how-to-edit-the-rst-documentation:how to add images>`.
-
-
 HTML and CSS
 ^^^^^^^^^^^^
 
@@ -237,35 +433,12 @@ Emphasis and Italics
     ``monospace``
 
 
-
 Paragraph
 ^^^^^^^^^
 
 Paragraphs are plain texts where indentation matters. Separate paragraphs by leaving a blank line between them.
 
 
-Tables
-^^^^^^^
-
-We adhere to the list tables directive by docutils as described `here <https://docutils.sourceforge.io/docs/ref/rst/directives.html#list-table-1>`__.
-
-A simple example would be:
-
-    .. code-block:: rst
-
-        .. list-table:: rst
-           :widths: 15 10
-           :header-rows: 1
-
-           * - Header 1
-             - Header 2
-           * - Cell 1
-             - Cell 2
-           * - Cell 3
-             - Cell 4
-
-
-
 Indentation
 ^^^^^^^^^^^
 
@@ -273,204 +446,28 @@ Use spaces instead of tabs. Use hanging indentations where appropriate.
 rST is identation sensitiv markup language, similar to Python, please maintain consistent indentation (3 spaces) for readability.
 
 
-Lists
-^^^^^
-
-Lists can be bullet lists (\*, +, -), enumerated lists (1., 2., etc.), definition lists, field lists.
-
-Nested lists must be separated from the parent list items by blank lines:
-
-.. code-block:: rst
-
-  - Item 1
-  - Item 2
-
-    - Subitem 2.1
-    - Subitem 2.2
-
-  - Item 3
-
-Numbered lists can be autonumbered using the ``#`` sign.
-
-.. code-block:: rst
-
-  #. Item 1
-  #. Item 2
-
-    #. Subitem 2.1
-    #. Subitem 2.2
-
-  #. Item 3
-
-Item 3 will start at 1.
-
-Code blocks
-^^^^^^^^^^^
-
-
-When writing code blocks, use syntax highlighting with the `code-block <https://www.sphinx-doc.org/en/master/usage/restructuredtext/directives.html#directive-code-block>`__
-or `code <https://www.sphinx-doc.org/en/master/usage/restructuredtext/directives.html#directive-code>`__  (see `here <https://pygments.org/languages/>`__ for a list of supported languages).
-
-.. code-block:: rst
-
-   .. code-block:: language
-
-     code
-
-By specifying the language, you enable pygments, which show syntax color coding for that code sample.
-
-Use ``[...]`` for anything omitted.
-
-You can add line numbers to code examples with the ``:linenos:`` parameter.
-
-.. code-block:: rst
-
-    .. code-block:: python
-      :linenos:
-
-       def hello_world():
-         print("Hello, world!")
-
-
-You can have certain lines with the ``:emphasize-lines:`` parameter.
-
-.. code-block:: rst
-
- .. code-block:: python
-   :emphasize-lines: 1,3,4
-
-
-
-For Python use ``python``.
-
-.. code-block:: rst
-
-    .. code-block:: python
-
-      string_var = 'python'
-
-For bash use ``bash``.
-
-.. code-block:: rst
-
-    .. code-block:: bash
-
-      echo "Hello"
-
-For bash session use ``console``.
-
-.. code-block:: rst
-
-    .. code-block:: console
-
-      pygments_style = 'sphinx'
-
-For text output use ``output``.
-
-.. code-block:: rst
-
-    .. code-block:: output
-
-       some output
-
-For text use ``text``.
-
-.. code-block:: rst
-
-    .. code-block:: text
-
-       some text
-
-
 Line wrapping
 ^^^^^^^^^^^^^
 
 Do not hard wrap text, except where necessary (e.g., inside code blocks).
 
-Admonitions, messages, and warnings
-^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
-
-
-`Admonitions, messages, and warnings <https://www.sphinx-doc.org/en/master/usage/restructuredtext/directives.html#admonitions-messages-and-warnings>`__ are used to draw the reader’s attention to important information, such as warnings, and for stylistic purposes.
-They are typically styled as colored text boxes, usually accompanied by icons provided out of the box by Sphinx and rST.
-Alerts should generally be used somewhat sparingly, so as not to cause `alert fatigue <https://en.wikipedia.org/wiki/Alarm_fatigue>`__.
-
-Here are examples of several types of alerts:
-
-.. code:: rst
-
-    .. hint::
-       **Did you know?** The Qubes OS installer is completely offline. It doesn't
-       even load any networking drivers, so there is no possibility of
-       internet-based data leaks or attacks during the installation process.
-
-     .. note::
-       **Note:*</b>** Using Rufus to create the installation medium means that you
-       `wont be able <https://github.com/QubesOS/qubes-issues/issues/2051">`__
-       to choose the "Test this media and install Qubes OS" option mentioned in the
-       example below. Instead, choose the "Install Qubes OS" option. TODO auto-build
-
-     .. warning::
-       **Note:** Qubes OS is not meant to be installed inside a virtual machine
-       as a guest hypervisor. In other words, **nested virtualization** is not
-       supported. In order for a strict compartmentalization to be enforced, Qubes
-       OS needs to be able to manage the hardware directly.
-
-     .. danger::
-       **Warning:** Qubes has no control over what happens on your computer
-       before you install it. No software can provide security if it is installed on
-       compromised hardware. Do not install Qubes on a computer you don't trust. See
-       installation security for more information.
-
-
-
-These render as:
-
-.. hint::
-       **Did you know?** The Qubes OS installer is completely offline. It doesn't
-       even load any networking drivers, so there is no possibility of
-       internet-based data leaks or attacks during the installation process.
-
-.. note::
-       **Note:** Using Rufus to create the installation medium means that you
-       `won't be able <"https://github.com/QubesOS/qubes-issues/issues/2051">`__
-       to choose the "Test this media and install Qubes OS" option mentioned in the
-       example below. Instead, choose the "Install Qubes OS" option.
-
-.. warning::
-       **Note:** Qubes OS is not meant to be installed inside a virtual machine
-       as a guest hypervisor. In other words, **nested virtualization** is not
-       supported. In order for a strict compartmentalization to be enforced, Qubes
-       OS needs to be able to manage the hardware directly.
-
-.. danger::
-       **Warning:** Qubes has no control over what happens on your computer
-       before you install it. No software can provide security if it is installed on
-       compromised hardware. Do not install Qubes on a computer you don't trust. See
-       installation security for more information.
-
-
 
 Writing guidelines
 ------------------
 
-
 Correct use of terminology
 ^^^^^^^^^^^^^^^^^^^^^^^^^^
 
-
 Familiarize yourself with the terms defined in the :doc:`glossary </user/reference/glossary>`. Use these terms consistently and accurately throughout your writing.
 
 Sentence case in headings
 ^^^^^^^^^^^^^^^^^^^^^^^^^
 
-
 Use sentence case (rather than title case) in headings for the reasons explained `here <https://www.sallybagshaw.com.au/articles/sentence-case-v-title-case/>`__. In particular, since the authorship of the Qubes documentation is decentralized and widely distributed among users from around the world, many contributors come from regions with different conventions for implementing title case, not to mention that there are often differing style guide recommendations even within a single region. It is much easier for all of us to implement sentence case consistently across our growing body of pages, which is very important for managing the ongoing maintenance burden and sustainability of the documentation.
 
 Writing command-line examples
 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
 
-
 When providing command-line examples:
 
 - Tell the reader where to open a terminal (dom0 or a specific domU), and show the command along with its output (if any) in a code block, e.g.:
@@ -501,7 +498,6 @@ When providing command-line examples:
  The ``#`` symbol preceding each comment is ambiguous with a root command prompt. Instead, put your comments *outside* of the code block in normal prose.
 
 
-
 Variable names in commands
 ^^^^^^^^^^^^^^^^^^^^^^^^^^
 
@@ -546,7 +542,7 @@ Capitalization of "qube"
 ^^^^^^^^^^^^^^^^^^^^^^^^
 
 
-We introduced the term :ref:`“qube” <user/reference/glossary:qube>` as a user-friendly alternative to the term :ref:`“virtual machine” (“VM”) <user/reference/glossary:vm>` in the context of Qubes OS. Nonetheless, “qube” is a common noun like the words “compartment” and “container.” Therefore, in English, “qube” follows the standard capitalization rules for common nouns. For example, “I have three qubes” is correct, while “I have three Qubes” is incorrect. Like other common nouns, “qube” should still be capitalized at the beginnings of sentences, the beginnings of sentence-case headings, and in title-case headings. Note, however, that starting a sentence with the plural of “qube” (e.g., “Qubes can be shut down…”) can be ambiguous, since it may not be clear whether the referent is a plurality of qubes, :ref:`Qubes OS <user/reference/glossary:qubes os>`, or even the Qubes OS Project itself. Hence, it is generally a good idea to rephrase such sentences in order to avoid this ambiguity.
+We introduced the term :term:`qube` as a user-friendly alternative to the term :term:`vm` in the context of Qubes OS. Nonetheless, “qube” is a common noun like the words “compartment” and “container.” Therefore, in English, “qube” follows the standard capitalization rules for common nouns. For example, “I have three qubes” is correct, while “I have three Qubes” is incorrect. Like other common nouns, “qube” should still be capitalized at the beginnings of sentences, the beginnings of sentence-case headings, and in title-case headings. Note, however, that starting a sentence with the plural of “qube” (e.g., “Qubes can be shut down…”) can be ambiguous, since it may not be clear whether the referent is a plurality of qubes, :term:`qubes os`, or even the Qubes OS Project itself. Hence, it is generally a good idea to rephrase such sentences in order to avoid this ambiguity.
 
 Many people feel a strong temptation to capitalize the word “qube” all the time, like a proper noun, perhaps because it’s a new and unfamiliar term that’s closely associated with a particular piece of software (namely, Qubes OS). However, these factors are not relevant to the capitalization rules of English. In fact, it’s not unusual for new common nouns to be introduced into English, especially in the context of technology. For example, “blockchain” is a relatively recent technical term that’s a common noun. Why is it a common noun rather than a proper noun? Because proper nouns refer to *particular* people, places, things, and ideas. There are many different blockchains. However, even when there was just one, the word still denoted a collection of things rather than a particular thing. It happened to be the case that there was only one member in that collection at the time. For example, if there happened to be only one tree in the world, that wouldn’t change the way we capitalize sentences like, “John sat under a tree.” Intuitively, it makes sense that the addition and removal of objects from the world shouldn’t cause published books to become orthographicallly incorrect while sitting on their shelves.
 
@@ -574,11 +570,11 @@ 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-documentation:how to edit the documentation index>`) to add and update Qubes Forum links in the :ref:`“External documentation” <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:`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.
 
 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.
 
-Many contributors do not realize that there is a significant amount of work involved in *maintaining* documentation after it has been written. They may wish to write documentation and submit it to the core docs, but they see only their own writing process and fail to consider that it will have to be kept up-to-date and consistent with the rest of the docs for years afterward. Submissions to the core docs also have to :ref:`undergo a review process <developer/general/how-to-edit-the-documentation:security>`__ to ensure accuracy before being merged, which takes up valuable time from the team. We aim to maintain high quality standards for the core docs (style and mechanics, formatting), which also takes up a lot of time. If the documentation involves anything external to the Qubes OS Project (such as a website, platform, program, protocol, framework, practice, or even a reference to a version number), the documentation is likely to become outdated when that external thing changes. It’s also important to periodically review and update this documentation, especially when a new Qubes release comes out. Periodically, there may be technical or policy changes that affect all the core documentation. The more documentation there is relative to maintainers, the harder all of this will be. Since there are many more people who are willing to write documentation than to maintain it, these individually small incremental additions amount to a significant maintenance burden for the project.
+Many contributors do not realize that there is a significant amount of work involved in *maintaining* documentation after it has been written. They may wish to write documentation and submit it to the core docs, but they see only their own writing process and fail to consider that it will have to be kept up-to-date and consistent with the rest of the docs for years afterward. Submissions to the core docs also have to :ref:`undergo a review process <developer/general/how-to-edit-the-rst-documentation:security>`__ to ensure accuracy before being merged, which takes up valuable time from the team. We aim to maintain high quality standards for the core docs (style and mechanics, formatting), which also takes up a lot of time. If the documentation involves anything external to the Qubes OS Project (such as a website, platform, program, protocol, framework, practice, or even a reference to a version number), the documentation is likely to become outdated when that external thing changes. It’s also important to periodically review and update this documentation, especially when a new Qubes release comes out. Periodically, there may be technical or policy changes that affect all the core documentation. The more documentation there is relative to maintainers, the harder all of this will be. Since there are many more people who are willing to write documentation than to maintain it, these individually small incremental additions amount to a significant maintenance burden for the project.
 
 On the positive side, we consider the existence of community documentation to be a sign of a healthy ecosystem, and this is quite common in the software world. The community is better positioned to write and maintain documentation that applies, combines, and simplifies the official documentation, e.g., tutorials that explain how to install and use various programs in Qubes, how to create custom VM setups, and introductory tutorials that teach basic Linux concepts and commands in the context of Qubes. In addition, just because the Qubes OS Project has officially written and maintains some flexible framework, such as ``qrexec``, it does not make sense to include every tutorial that says “here’s how to do something cool with ``qrexec`` in the core docs. Such tutorials generally also belong in the community documentation.
 
@@ -629,7 +625,7 @@ Correct Example
 ^^^^^^^^^^^^^^^
 
 
-.. code:: te
+.. code:: rst
 
      Qubes 3.2
      =========
@@ -642,7 +638,9 @@ Correct Example
      the most part, all fooing is fooing.
 
      To foo:
+
         .. code-block:: console
+
            $ qvm-foo <foo-bar>
 
      Once you foo, make sure to close the baz before fooing the next bar.
@@ -662,6 +660,7 @@ Correct Example
      general ``qubes-baz`` command:
 
         .. code-block:: console
+
           $ qubes-baz --foo <bar>
 
      Once you foo, make sure to close the baz before fooing the next bar.

developer/general/website-style-guide.rst

@@ -3,12 +3,12 @@ Website style guide
 ===================
 
 
-This page explains the standards we follow for building and maintaining the website. Please follow these guidelines and conventions when modifying the website. For the standards governing the documentation in particular, please see the :doc:`documentation style guide </developer/general/documentation-style-guide>`.
+This page explains the standards we follow for building and maintaining the website. Please follow these guidelines and conventions when modifying the website. For the standards governing the documentation in particular, please see the :doc:`documentation style guide </developer/general/rst-documentation-style-guide>`.
+
 
 Coding conventions
 ------------------
 
-
 The following conventions apply to the website as a whole, including everything written in HTML, CSS, YAML, and Liquid. These conventions are intended to keep the codebase consistent when multiple collaborators are working on it. They should be understood as a practical set of rules for maintaining order in this specific codebase rather than as a statement of what is objectively right or good.
 
 General practices
@@ -23,34 +23,22 @@ General practices
 
 - `Don’t Repeat Yourself (DRY)! <https://en.wikipedia.org/wiki/Don%27t_repeat_yourself>`__ Instead of repeating the same block of code multiple times, abstract it out into a separate file and ``include`` that file where you need it.
 
-
-
 Whitespace
 ^^^^^^^^^^
 
-
 - Always use spaces. Never use tabs.
-
 - Each indentation step should be exactly two (2) spaces.
-
 - Whenever you add an opening tag, indent the following line. (Exception: If you open and close the tag on the same line, do not indent the following line.)
-
 - Indent Liquid the same way as HTML.
-
 - In general, the starting columns of every adjacent pair of lines should be no more than two spaces apart (example below).
-
 - No blank or empty lines. (Hint: When you feel you need one, add a comment on that line instead.)
 
 
-
 Indentation example
 ^^^^^^^^^^^^^^^^^^^
 
-
 Here’s an example that follows the indentation rules:
 
-
-
 .. code:: html
 
       <table>
@@ -70,4 +58,342 @@ Here’s an example that follows the indentation rules:
       </table>
 
 
+Markdown style guide and conventions
+------------------------------------
 
+
+*Also see* :doc:`how to edit the website </developer/general/how-to-edit-the-website>`.
+
+Some of the Qubes OS website pages are stored as plain text Markdown files in the `qubesos.github.io <https://github.com/QubesOS/qubesos.github.io>`__ repository.
+
+
+Markdown conventions
+^^^^^^^^^^^^^^^^^^^^
+
+When making contributions to Markdown files, please observe the following style conventions. If you’re not familiar with Markdown syntax, `this <https://daringfireball.net/projects/markdown/>`__ is a great resource.
+
+Hyperlink syntax
+^^^^^^^^^^^^^^^^
+
+Use non-reference-style links like :code:`[website](https://example.com/)`. Do *not* use reference-style links like ``[website][example]``, ``[website][]`` or ``[website]``. This facilitates the localization process.
+
+Relative vs. absolute links
+^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+Always use relative rather than absolute paths for internal website links. For example, use ``/donate/`` instead of ``https://www.qubes-os.org/donate/``.
+
+You may use absolute URLs in the following cases:
+
+- External links
+- URLs that appear inside code blocks (e.g., in comments and document templates, and the plain text reproductions of `QSBs <https://www.qubes-os.org/security/qsb/>`__ and `Canaries <https://www.qubes-os.org/security/canary/>`__), since they’re not hyperlinks
+- Git repo files like ``README.md`` and ``CONTRIBUTING.md``, since they’re not part of the website itself but rather of the auxiliary infrastructure supporting the website
+
+
+This rule is important because using absolute URLs for internal website links breaks:
+
+- Serving the website offline
+- Website localization
+- Generating offline documentation
+- Automatically redirecting Tor Browser visitors to the correct page on the onion service mirror
+
+
+Image linking
+^^^^^^^^^^^^^
+
+To add an image to a page, use the following syntax in the main document.
+
+.. code:: markdown
+
+  [![Image Title](/attachment/doc/image.png)](/attachment/doc/image.png)
+
+This will make the image a hyperlink to the image file, allowing the reader to click on the image in order to view the full image by itself. This is important. Following best practices, our website has a responsive design, which allows the website to render appropriately across all screen sizes. When viewing this page on a smaller screen, such as on a mobile device, the image will automatically shrink down to fit the screen. If visitors cannot click on the image to view it in full size, then, depending on their device, they may have no way see the details in the image clearly.
+
+In addition, make sure to link only to images in the `qubes-attachment <https://github.com/QubesOS/qubes-attachment>`__ repository. Do not attempt to link to images hosted on other websites.
+
+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.
+
+Headings
+^^^^^^^^
+
+Do not use ``h1`` headings (single ``#`` or ``======`` underline). These are automatically generated from the ``title:`` line in the YAML front matter.
+
+Use Atx-style syntax for headings: ``##h2``, ``### h3``, etc. Do not use underlining syntax (``-----``).
+
+Indentation
+^^^^^^^^^^^
+
+Use spaces instead of tabs. Use hanging indentations where appropriate.
+
+Lists
+^^^^^
+
+If appropriate, make numerals in numbered lists match between Markdown source and HTML output. Some users read the Markdown source directly, and this makes numbered lists easier to follow.
+
+Code blocks
+^^^^^^^^^^^
+
+When writing code blocks, use `syntax highlighting <https://github.github.com/gfm/#info-string>`__ where possible (see `here <https://github.com/jneen/rouge/wiki/List-of-supported-languages-and-lexers>`__ for a list of supported languages). Use ``[...]`` for anything omitted.
+
+Line wrapping
+^^^^^^^^^^^^^
+
+Do not hard wrap text, except where necessary (e.g., inside code blocks).
+
+Do not use Markdown syntax for styling
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+For example, there is a common temptation to use block quotations (created by beginning lines with the ``>`` character) in order to stylistically distinguish some portion of text from the rest of the document, e.g.:
+
+.. code:: bash
+
+      > **Note:** This is an important note!
+
+
+
+This renders as:
+
+   **Note:** This is an important note!
+
+There are two problems with this:
+
+1. It is a violation of the `separation of content and presentation <https://en.wikipedia.org/wiki/Separation_of_content_and_presentation>`__, since it abuses markup syntax in order to achieve unintended stylistic results. The Markdown (and HTML, if any) should embody the *content* of the documentation, while the *presentation* is handled by (S)CSS.
+
+2. It is an abuse of quotation syntax for text that is not actually a quotation. (You are not quoting anyone here. You’re just telling the reader to note something and trying to draw their attention to your note visually.)
+
+
+
+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.,:
+
+.. code:: bash
+
+      **Note:** This is an important note.
+
+
+This renders as:
+
+**Note:** This is an important note.
+
+Alerts
+^^^^^^
+
+Alerts are sections of HTML used to draw the reader’s attention to important information, such as warnings, and for stylistic purposes. They are typically styled as colored text boxes, usually accompanied by icons. Alerts should generally be used somewhat sparingly, so as not to cause `alert fatigue <https://en.wikipedia.org/wiki/Alarm_fatigue>`__ and since they must be written in HTML instead of Markdown, which makes the source less readable and more difficult to work with for localization and automation purposes. Here are examples of several types of alerts and their recommended icons:
+
+.. code:: html
+
+      <div class="alert alert-success" role="alert">
+        <i class="fa fa-check-circle"></i>
+        <b>Did you know?</b> The Qubes OS installer is completely offline. It doesn't
+        even load any networking drivers, so there is no possibility of
+        internet-based data leaks or attacks during the installation process.
+      </div>
+
+      <div class="alert alert-info" role="alert">
+        <i class="fa fa-info-circle"></i>
+        <b>Note:</b> Using Rufus to create the installation medium means that you <a
+        href="https://github.com/QubesOS/qubes-issues/issues/2051">won't be able</a>
+        to choose the "Test this media and install Qubes OS" option mentioned in the
+        example below. Instead, choose the "Install Qubes OS" option.
+      </div>
+
+      <div class="alert alert-warning" role="alert">
+        <i class="fa fa-exclamation-circle"></i>
+        <b>Note:</b> Qubes OS is not meant to be installed inside a virtual machine
+        as a guest hypervisor. In other words, <b>nested virtualization</b> is not
+        supported. In order for a strict compartmentalization to be enforced, Qubes
+        OS needs to be able to manage the hardware directly.
+      </div>
+
+      <div class="alert alert-danger" role="alert">
+        <i class="fa fa-exclamation-triangle"></i>
+        <b>Warning:</b> Qubes has no control over what happens on your computer
+        before you install it. No software can provide security if it is installed on
+        compromised hardware. Do not install Qubes on a computer you don't trust. See
+        [installation security](/doc/install-security/) for more
+        information.
+      </div>
+
+
+
+These render as:
+
+|alerts|
+
+Writing guidelines
+^^^^^^^^^^^^^^^^^^
+
+Correct use of terminology
+^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+Familiarize yourself with the terms defined in the :doc:`glossary </user/reference/glossary>`. Use these terms consistently and accurately throughout your writing.
+
+Sentence case in headings
+^^^^^^^^^^^^^^^^^^^^^^^^^
+
+Use sentence case (rather than title case) in headings for the reasons explained `here <https://www.sallybagshaw.com.au/articles/sentence-case-v-title-case/>`__. In particular, since the authorship of the Qubes documentation is decentralized and widely distributed among users from around the world, many contributors come from regions with different conventions for implementing title case, not to mention that there are often differing style guide recommendations even within a single region. It is much easier for all of us to implement sentence case consistently across our growing body of pages, which is very important for managing the ongoing maintenance burden and sustainability of the documentation.
+
+Writing command-line examples
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+When providing command-line examples:
+
+- Tell the reader where to open a terminal (dom0 or a specific domU), and show the command along with its output (if any) in a code block, e.g.:
+
+  .. code:: bash
+
+        Open a terminal in dom0 and run:
+        ```
+        $ cd test
+        $ echo Hello
+        Hello
+        ```
+
+- Precede each command with the appropriate command prompt: At a minimum, the prompt should contain a trailing ``#`` (for the user ``root``) or ``$`` (for other users) on Linux systems and ``>`` on Windows systems, respectively.
+- Don’t try to add comments inside the code block. For example, *don’t* do this:
+
+  .. code:: bash
+
+        Open a terminal in dom0 and run:
+        ```
+        # Navigate to the new directory
+        $ cd test
+        # Generate a greeting
+        $ echo Hello
+        Hello
+        ```
+
+  The ``#`` symbol preceding each comment is ambiguous with a root command prompt. Instead, put your comments *outside* of the code block in normal prose.
+
+
+
+Variable names in commands
+^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+Syntactically distinguish variables in commands. For example, this is ambiguous:
+
+.. code:: bash
+
+      $ qvm-run --dispvm=disposable-template --service qubes.StartApp+xterm
+
+It should instead be:
+
+.. code:: bash
+
+      $ qvm-run --dispvm=<DISPOSABLE_TEMPLATE> --service qubes.StartApp+xterm
+
+Note that we syntactically distinguish variables in three ways:
+
+1. Surrounding them in angled brackets (``< >``)
+
+2. Using underscores (``_``) instead of spaces between words
+
+3. Using all capital letters
+
+
+
+We have observed that many novices make the mistake of typing the surrounding angled brackets (``< >``) on the command line, even after substituting the desired real value between them. Therefore, in documentation aimed at novices, we also recommend clarifying that the angled brackets should not be typed. This can be accomplished in one of several ways:
+
+- Explicitly say something like “without the angled brackets.”
+- Provide an example command using real values that excludes the angled brackets.
+- If you know that almost all users will want to use (or should use) a specific command containing all real values and no variables, you might consider providing exactly that command and forgoing the version with variables. Novices may not realize which parts of the command they can substitute with different values, but if you’ve correctly judged that they should use the command you’ve provided as is, then this shouldn’t matter.
+
+
+Capitalization of "qube"
+^^^^^^^^^^^^^^^^^^^^^^^^
+
+We introduced the term :term:`qube` as a user-friendly alternative to the term :term:`vm` in the context of Qubes OS. Nonetheless, “qube” is a common noun like the words “compartment” and “container.” Therefore, in English, “qube” follows the standard capitalization rules for common nouns. For example, “I have three qubes” is correct, while “I have three Qubes” is incorrect. Like other common nouns, “qube” should still be capitalized at the beginnings of sentences, the beginnings of sentence-case headings, and in title-case headings. Note, however, that starting a sentence with the plural of “qube” (e.g., “Qubes can be shut down…”) can be ambiguous, since it may not be clear whether the referent is a plurality of qubes, :term:`qubes os`, or even the Qubes OS Project itself. Hence, it is generally a good idea to rephrase such sentences in order to avoid this ambiguity.
+
+Many people feel a strong temptation to capitalize the word “qube” all the time, like a proper noun, perhaps because it’s a new and unfamiliar term that’s closely associated with a particular piece of software (namely, Qubes OS). However, these factors are not relevant to the capitalization rules of English. In fact, it’s not unusual for new common nouns to be introduced into English, especially in the context of technology. For example, “blockchain” is a relatively recent technical term that’s a common noun. Why is it a common noun rather than a proper noun? Because proper nouns refer to *particular* people, places, things, and ideas. There are many different blockchains. However, even when there was just one, the word still denoted a collection of things rather than a particular thing. It happened to be the case that there was only one member in that collection at the time. For example, if there happened to be only one tree in the world, that wouldn’t change the way we capitalize sentences like, “John sat under a tree.” Intuitively, it makes sense that the addition and removal of objects from the world shouldn’t cause published books to become orthographicallly incorrect while sitting on their shelves.
+
+Accordingly, the reason “qube” is a common noun rather than a proper noun is because it doesn’t refer to any one specific thing (in this case, any one specific virtual machine). Rather, it’s the term for any virtual machine in a Qubes OS installation. (Technically, while qubes are currently implemented as virtual machines, Qubes OS is independent of its underlying compartmentalization technology. Virtual machines could be replaced with a different technology, and qubes would still be called “qubes.”)
+
+I have several qubes in my Qubes OS installation, and you have several in yours. Every Qubes OS user has their own set of qubes, just as each of us lives in some neighborhood on some street. Yet we aren’t tempted to treat words like “neighborhood” or “street” as proper nouns (unless, of course, they’re part of a name, like “Acorn Street”). Again, while this might seem odd because “qube” is a new word that we invented, that doesn’t change how English works. After all, *every* word was a new word that someone invented at some point (otherwise we wouldn’t have any words at all). We treat “telephone,” “computer,” “network,” “program,” and so on as common nouns, even though those were all new technological inventions in the not-too-distant past (on a historical scale, at least). So, we shouldn’t allow ourselves to be confused by irrelevant factors, like the fact that the inventors happened to be *us* or that the invention was *recent* or is not in widespread use among humanity.
+
+English language conventions
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+For the sake of consistency and uniformity, the Qubes documentation aims to follow the conventions of American English, where applicable. (Please note that this is an arbitrary convention for the sake consistency and not a value judgment about the relative merits of British versus American English.)
+
+
+Incorrect Example
+^^^^^^^^^^^^^^^^^
+
+.. code:: bash
+
+      ## How to Foo
+
+      Fooing is the process by which one foos. There are both general and specific
+      versions of fooing, which vary in usefulness depending on your goals, but for
+      the most part, all fooing is fooing.
+
+      To foo in Qubes 3.2:
+
+         $ qvm-foo <foo-bar>
+
+      Note that this does not work in Qubes 4.0, where there is a special widget
+      for fooing, which you can find in the lower-right corner of the screen in
+      the Foo Manager. Alternatively, you can use the more general `qubes-baz`
+      command introduced in 4.0:
+
+         $ qubes-baz --foo <bar>
+
+      Once you foo, make sure to close the baz before fooing the next bar.
+
+
+Correct Example
+^^^^^^^^^^^^^^^
+
+.. code:: bash
+
+      ## Qubes 3.2
+
+      ### How to Foo
+
+      Fooing is the process by which one foos. There are both general and specific
+      versions of fooing, which vary in usefulness depending on your goals, but for
+      the most part, all fooing is fooing.
+
+      To foo:
+
+         $ qvm-foo <foo-bar>
+
+      Once you foo, make sure to close the baz before fooing the next bar.
+
+      ## Qubes 4.0
+
+      ### How to Foo
+
+      Fooing is the process by which one foos. There are both general and specific
+      versions of fooing, which vary in usefulness depending on your goals, but for
+      the most part, all fooing is fooing.
+
+      There is a special widget for fooing, which you can find in the lower-right
+      corner of the screen in the Foo Manager. Alternatively, you can use the
+      general `qubes-baz` command:
+
+         $ qubes-baz --foo <bar>
+
+      Once you foo, make sure to close the baz before fooing the next bar.
+
+
+Subdividing the page into clearly-labeled sections for each release has several benefits:
+
+- It preserves good content for older (but still supported) releases. Many documentation contributors are also people who prefer to use the latest release. Many of them are tempted to *replace* existing content that applies to an older, supported release with content that applies only to the latest release. This is somewhat understandable. Since they only use the latest release, they may be focused on their own experience, and they may even regard the older release as deprecated, even when it’s actually still supported. However, allowing this replacement of content would do a great disservice to those who still rely on the older, supported release. In many cases, these users value the stability and reliability of the older, supported release. With the older, supported release, there has been more time to fix bugs and make improvements in both the software and the documentation. Consequently, much of the documentation content for this release may have gone through several rounds of editing, review, and revision. It would be a tragedy for this content to vanish while the very set of users who most prize stability and reliability are depending on it.
+- It’s easy for readers to quickly find the information they’re looking for, since they can go directly to the section that applies to their release.
+- It’s hard for readers to miss information they need, since it’s all in one place. In the incorrect example, information that the reader needs could be in any paragraph in the entire document, and there’s no way to tell without reading the entire page. In the correct example, the reader can simply skim the headings in order to know which parts of the page need to be read and which can be safely ignored. The fact that some content is repeated in the two release-specific sections is not a problem, since no reader has to read the same thing twice. Moreover, as one release gets updated, it’s likely that the documentation for that release will also be updated. Therefore, content that is initially duplicated between release-specific sections will not necessarily stay that way, and this is a good thing: We want the documentation for a release that *doesn’t* change to stay the same, and we want the documentation for a release that *does* change to change along with the software.
+- It’s easy for documentation contributors and maintainers to know which file to edit and update, since there’s only one page for all Qubes OS releases. Initially creating the new headings and duplicating content that applies to both is only a one-time cost for each page, and many pages don’t even require this treatment, since they apply to all currently-supported Qubes OS releases.
+
+
+By contrast, an alternative approach, such as segregating the documentation into two different branches, would mean that contributions that apply to both Qubes releases would only end up in one branch, unless someone remembered to manually submit the same thing to the other branch and actually made the effort to do so. Most of the time, this wouldn’t happen. When it did, it would mean a second pull request that would have to be reviewed. Over time, the different branches would diverge in non-release-specific content. Good general content that was submitted only to one branch would effectively disappear once that release was deprecated. (Even if it were still on the website, no one would look at it, since it would explicitly be in the subdirectory of a deprecated release, and there would be a motivation to remove it from the website so that search results wouldn’t be populated with out-of-date information.)
+
+For further discussion about release-specific documentation in Qubes, see `here <https://groups.google.com/d/topic/qubes-users/H9BZX4K9Ptk/discussion>`__.
+
+Git conventions
+---------------
+
+Please follow our :ref:`Git commit message guidelines <developer/code/coding-style:commit message guidelines>`.
+
+.. |alerts| image:: /attachment/doc/website_alerts.png

index.rst

@@ -211,7 +211,6 @@ Core documentation for Qubes developers and advanced users.
    developer/general/how-to-edit-the-rst-documentation
    developer/general/rst-documentation-style-guide
    developer/general/how-to-edit-the-website
-   developer/general/markdown-style-guide
    developer/general/website-style-guide
    developer/general/continuous-integration
    developer/general/usability-ux

introduction/contributing.rst

@@ -23,7 +23,7 @@ Thank you for your interest in contributing to Qubes! Here are some of the many
 
 - Create `artwork <https://github.com/QubesOS/qubes-artwork>`__ (plymouth themes, installer themes, wallpapers, etc.)
 
-- :doc:`Write and edit the documentation </developer/general/how-to-edit-the-documentation>`
+- :doc:`Write and edit the documentation </developer/general/how-to-edit-the-rst-documentation>`
 
 - `Donate <https://www.qubes-os.org/donate/>`__ to the project
 

introduction/faq.rst

@@ -320,7 +320,7 @@ Should I trust this website?
 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^
 
 
-This website is hosted on `GitHub Pages <https://pages.github.com/>`__ (`why? <#why-do-you-use-github>`__). Therefore, it is largely outside of our control. We don’t consider this a problem, however, since we explicitly `distrust the infrastructure <#what-does-it-mean-to-distrust-the-infrastructure>`__. For this reason, we don’t think that anyone should place undue trust in the live version of this site on the Web. Instead, if you want to obtain your own trustworthy copy of this website in a secure way, you should clone our `website repo <https://github.com/QubesOS/qubesos.github.io>`__, :ref:`verify the PGP signatures on the commits and/or tags <project-security/verifying-signatures:how to verify signatures on git repository tags and commits>` signed by the `doc-signing keys <https://github.com/QubesOS/qubes-secpack/tree/master/keys/doc-signing>`__ (which indicates that the content has undergone :ref:`review <developer/general/how-to-edit-the-documentation:security>`), then either `render the site on your local machine <https://github.com/QubesOS/qubesos.github.io/blob/master/README.md#instructions>`__ or simply read the source, the vast majority of which was :ref:`intentionally written in Markdown so as to be readable as plain text for this very reason <developer/general/documentation-style-guide:markdown conventions>`. We’ve gone to special effort to set all of this up so that no one has to trust the infrastructure and so that the contents of this website are maximally available and accessible.
+This website is hosted on `GitHub Pages <https://pages.github.com/>`__ (`why? <#why-do-you-use-github>`__). Therefore, it is largely outside of our control. We don’t consider this a problem, however, since we explicitly `distrust the infrastructure <#what-does-it-mean-to-distrust-the-infrastructure>`__. For this reason, we don’t think that anyone should place undue trust in the live version of this site on the Web. Instead, if you want to obtain your own trustworthy copy of this website in a secure way, you should clone our `website repo <https://github.com/QubesOS/qubesos.github.io>`__, :ref:`verify the PGP signatures on the commits and/or tags <project-security/verifying-signatures:how to verify signatures on git repository tags and commits>` signed by the `doc-signing keys <https://github.com/QubesOS/qubes-secpack/tree/master/keys/doc-signing>`__ (which indicates that the content has undergone :ref:`review <developer/general/how-to-edit-the-website:security>`), then either `render the site on your local machine <https://github.com/QubesOS/qubesos.github.io/blob/master/README.md#instructions>`__ or simply read the source, the vast majority of which was :ref:`intentionally written in Markdown so as to be readable as plain text for this very reason <developer/general/website-style-guide:markdown conventions>`. We’ve gone to special effort to set all of this up so that no one has to trust the infrastructure and so that the contents of this website are maximally available and accessible.
 
 
 What does it mean to "distrust the infrastructure"?

introduction/getting-started.rst

@@ -189,7 +189,7 @@ 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-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
    

introduction/issue-tracking.rst

@@ -21,7 +21,7 @@ I see something that should be changed in the documentation.
 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
 
 
-We encourage you to submit the change yourself! Please see the :doc:`how to edit the documentation </developer/general/how-to-edit-the-documentation>` for instructions on how to do so. If it’s something you can’t do yourself, please proceed to open an issue.
+We encourage you to submit the change yourself! Please see the :doc:`how to edit the documentation </developer/general/how-to-edit-the-rst-documentation>` for instructions on how to do so. If it’s something you can’t do yourself, please proceed to open an issue.
 
 I would like to report a security vulnerability.
 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^

introduction/support.rst

@@ -77,7 +77,7 @@ It’s always possible that a bad actor could try to impersonate any member of t
 
 Given that there may be impostors and others trying to lead you astray, how should you sort the good advice from the bad? This is up to each individual to decide, but it helps to know that many members of our community have proven themselves knowledgeable through their :doc:`contributions </introduction/contributing>` to the project. Often, these individuals sign their messages with the same key as (or another key authenticated by) the one they use to :doc:`sign their contributions </developer/code/code-signing>`.
 
-For example, you might find it easier to trust advice from someone who has a proven track record of :doc:`contributing software packages </developer/general/package-contributions>` or :doc:`contributing to the documentation </developer/general/how-to-edit-the-documentation>`. It’s unlikely that individuals who have worked hard to build good reputations for themselves through their contributions over the years would risk giving malicious advice in signed messages to public mailing lists. Since every contribution to the Qubes OS Project is publicly visible and cryptographically signed, anyone would be in a position to :doc:`verify </project-security/verifying-signatures>` that these came from the same keyholder.
+For example, you might find it easier to trust advice from someone who has a proven track record of :doc:`contributing software packages </developer/general/package-contributions>` or :doc:`contributing to the documentation </developer/general/how-to-edit-the-rst-documentation>`. It’s unlikely that individuals who have worked hard to build good reputations for themselves through their contributions over the years would risk giving malicious advice in signed messages to public mailing lists. Since every contribution to the Qubes OS Project is publicly visible and cryptographically signed, anyone would be in a position to :doc:`verify </project-security/verifying-signatures>` that these came from the same keyholder.
 
 Discussion guidelines
 ---------------------
@@ -121,7 +121,7 @@ Report issues and submit changes in the right places
 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
 
 
-The mailing lists and `forum <#forum>`__ are good places to ask questions and discuss things. However, if you’re submitting a more formal report, we’d prefer that you submit it to our :doc:`issue tracker </introduction/issue-tracking>` so that it doesn’t get overlooked. (However, please remember that :ref:`the issue tracker is not a discussion forum <introduction/issue-tracking:the issue tracker is not a discussion forum>`.) Likewise, if you see that something in the documentation should be changed, don’t simply point it out in a discussion venue. Instead, :doc:`submit the change </developer/general/how-to-edit-the-documentation>`.
+The mailing lists and `forum <#forum>`__ are good places to ask questions and discuss things. However, if you’re submitting a more formal report, we’d prefer that you submit it to our :doc:`issue tracker </introduction/issue-tracking>` so that it doesn’t get overlooked. (However, please remember that :ref:`the issue tracker is not a discussion forum <introduction/issue-tracking:the issue tracker is not a discussion forum>`.) Likewise, if you see that something in the documentation should be changed, don’t simply point it out in a discussion venue. Instead, :doc:`submit the change </developer/general/how-to-edit-the-rst-documentation>`.
 
 Moderation
 ^^^^^^^^^^

pyproject.toml

@@ -2,25 +2,25 @@
 name = "qubes-doc"
 version = "4.2"
 description = "Qubes OS documentation"
-authors = [
-    {name = "Qubes OS"}
-]
-readme = "README.md"
+authors = [{ name = "Qubes OS" }]
 requires-python = ">=3.11"
-dependencies = [
-    "sphinx (>=8.2.3,<9.0.0)"
-]
-
+readme = "README.md"
+dependencies = ["sphinx (>=8.2.3,<9.0.0)"]
 
 [build-system]
-requires = ["poetry-core>=2.0.0,<3.0.0"]
-build-backend = "poetry.core.masonry.api"
+requires = ["hatchling"]
+build-backend = "hatchling.build"
 
-[tool.poetry.group.dev.dependencies]
-sphinx = "^8.2.3"
-sphinx-autobuild = "^2024.10.3"
-sphinx-lint = "^1.0.0"
-sphinx-reredirects = "^1.0.0"
-sphinxnotes-strike = "^1.2.1"
-sphinx-rtd-theme = "^3.0.2"
+[tool.uv]
+package = false
+
+[dependency-groups]
+dev = [
+    "sphinx>=8.2.3,<9",
+    "sphinx-autobuild>=2024.10.3,<2025",
+    "sphinx-lint>=1.0.0,<2",
+    "sphinx-reredirects>=1.0.0,<2",
+    "sphinxnotes-strike>=1.2.1,<2",
+    "sphinx-rtd-theme>=3.0.2,<4",
+]
 

user/downloading-installing-upgrading/installation-guide-4.1.rst

@@ -345,7 +345,7 @@ Getting help
 ------------
 
 
-- We work very hard to make the :doc:`documentation </index>` accurate, comprehensive useful and user friendly. We urge you to read it! It may very well contain the answers to your questions. (Since the documentation is a community effort, we’d also greatly appreciate your help in :doc:`improving </developer/general/how-to-edit-the-documentation>` it!)
+- We work very hard to make the :doc:`documentation </index>` accurate, comprehensive useful and user friendly. We urge you to read it! It may very well contain the answers to your questions. (Since the documentation is a community effort, we’d also greatly appreciate your help in :doc:`improving </developer/general/how-to-edit-the-rst-documentation>` it!)
 
 - If issues arise during installation, see the :doc:`Installation Troubleshooting </user/troubleshooting/installation-troubleshooting>` guide.
 

user/downloading-installing-upgrading/installation-guide.rst

@@ -333,7 +333,7 @@ Getting help
 ------------
 
 
-- We work very hard to make the :doc:`documentation </index>` accurate, comprehensive useful and user friendly. We urge you to read it! It may very well contain the answers to your questions. (Since the documentation is a community effort, we’d also greatly appreciate your help in :doc:`improving </developer/general/how-to-edit-the-documentation>` it!)
+- We work very hard to make the :doc:`documentation </index>` accurate, comprehensive useful and user friendly. We urge you to read it! It may very well contain the answers to your questions. (Since the documentation is a community effort, we’d also greatly appreciate your help in :doc:`improving </developer/general/how-to-edit-the-rst-documentation>` it!)
 
 - If issues arise during installation, see the :doc:`Installation Troubleshooting </user/troubleshooting/installation-troubleshooting>` guide.
 

user/how-to-guides/how-to-enter-fullscreen-mode.rst

@@ -41,7 +41,7 @@ Other examples of such mechanisms are the KDE “Present Windows” and “Deskt
 Safely enabling fullscreen mode for a selected window
 -----------------------------------------------------
 
-You can always put a window into fullscreen mode in Xfce4 using the trusted window manager by right-clicking on a window’s title bar and selecting :guilabel:`Fullscreen` or pressing :kbd:`Alt` + :kbd:`F11`. This functionality should still be considered safe, since a qube window still can’t voluntarily enter fullscreen mode. The user must select this option from the trusted window manager in dom0. To exit fullscreen mode from here, press :kbd:`Alt` + :kbd:`Space` to bring up the title bar menu again, then select :guilabel:`Leave Fullscreen` or simply press :kbd:`Alt` + :kbd:`F11`. For :ref:`standalone HVMs <user/reference/glossary:HVM>`, you should set the screen resolution in the qube to that of the host, (or larger), *before* setting fullscreen mode in Xfce4.
+You can always put a window into fullscreen mode in Xfce4 using the trusted window manager by right-clicking on a window’s title bar and selecting :guilabel:`Fullscreen` or pressing :kbd:`Alt` + :kbd:`F11`. This functionality should still be considered safe, since a qube window still can’t voluntarily enter fullscreen mode. The user must select this option from the trusted window manager in dom0. To exit fullscreen mode from here, press :kbd:`Alt` + :kbd:`Space` to bring up the title bar menu again, then select :guilabel:`Leave Fullscreen` or simply press :kbd:`Alt` + :kbd:`F11`. For :term:`HVM`, you should set the screen resolution in the qube to that of the host, (or larger), *before* setting fullscreen mode in Xfce4.
 
 .. image:: /attachment/doc/how-to-enter-fullscreen-mode/fullscreen-from-dom0-dropdown.png
    :alt:

user/templates/debian/debian.rst

@@ -3,7 +3,7 @@ Debian templates
 ================
 
 
-The Debian :ref:`/user/reference/glossary:template` is an officially :ref:`supported <user/downloading-installing-upgrading/supported-releases:templates>` template in Qubes OS. The Current version is Debian |debian-version| (“|debian-codename|”). It is available in 3 versions - ``debian-12``, a standard template; ``debian-12-xfce``, a larger template with more installed applications, selected for :doc:`Xfce </user/templates/xfce-templates>`; ``debian-12-minimal``. This page is about the “full” templates. For the minimal version, please see the :doc:`Minimal templates </user/templates/minimal-templates>` page.
+The Debian :term:`template` is an officially :ref:`supported <user/downloading-installing-upgrading/supported-releases:templates>` template in Qubes OS. The Current version is Debian |debian-version| (“|debian-codename|”). It is available in 3 versions - ``debian-12``, a standard template; ``debian-12-xfce``, a larger template with more installed applications, selected for :doc:`Xfce </user/templates/xfce-templates>`; ``debian-12-minimal``. This page is about the “full” templates. For the minimal version, please see the :doc:`Minimal templates </user/templates/minimal-templates>` page.
 
 Installing
 ----------

user/templates/minimal-templates.rst

@@ -14,7 +14,7 @@ Important
 
 1. `The minimal templates are intended only for advanced users. <https://forum.qubes-os.org/t/9717/15>`__ Most things will *not* work out-of-the-box, and you *will* have to fix them yourself. If you are not prepared to do a lot of reading, searching, learning, and troubleshooting, then you should instead stick to the standard templates, which are perfectly suitable for the vast majority of users. In particular, if you are new to Qubes, you should not attempt to use minimal templates until you have gained more experience.
 
-2. If something works with a standard template but not the minimal version, this is most likely due to user error (e.g., a missing package or misconfiguration) rather than a bug. In such cases, please do *not* file a bug report. Instead, please see :doc:`Help, Support, Mailing Lists, and Forum </introduction/support>` for the appropriate place to ask for help. Once you have learned how to solve your problem, please :doc:`contribute what you learned to the documentation </developer/general/how-to-edit-the-documentation>`.
+2. If something works with a standard template but not the minimal version, this is most likely due to user error (e.g., a missing package or misconfiguration) rather than a bug. In such cases, please do *not* file a bug report. Instead, please see :doc:`Help, Support, Mailing Lists, and Forum </introduction/support>` for the appropriate place to ask for help. Once you have learned how to solve your problem, please :doc:`contribute what you learned to the documentation </developer/general/how-to-edit-the-rst-documentation>`.
 
 3. The minimal templates are intentionally *minimal*. :ref:`Do not ask for your favorite package to be added to the minimal template by default. <introduction/faq:could you please make my preference the default?>`