merge upstream and add rst version of the how to edit Markdown and Markdown and website style guide docs

introduction/intro.rst

@@ -1,3 +1,8 @@
+:og:image: https://doc.qubes-os.org/en/latest/_images/qubes-trust-level-architecture.png
+:og:image:alt: An overview of the security features of Qubes OS, including strong isolation, templating system,...
+:og:image:width: 778
+:og:image:height: 591
+
 ============
 Introduction
 ============
@@ -6,11 +11,11 @@ What is Qubes OS?
 -----------------
 
 Qubes OS is a free and open-source, security-oriented operating system for
-single-user desktop computing. Qubes OS leverages `Xen-based virtualization <https://wiki.xen.org/wiki/Xen_Project_Software_Overview>`__ to allow for the creation and management of isolated compartments called :ref:`qubes <user/reference/glossary:qube>`.
+single-user desktop computing. Qubes OS `leverages Xen-based virtualization <https://wiki.xen.org/wiki/Xen_Project_Software_Overview>`__ to allow for the creation and management of isolated compartments called :term:`qubes <qube>`.
 
 
-These qubes, which are implemented as :ref:`virtual machines (VMs)<user/reference/glossary:vm>`, have specific:
-
+These qubes, which are implemented as :term:`virtual machines (VMs) <vm>`, have specific:
+               
 - **Purposes:** with a predefined set of one or many isolated
   applications, for personal or professional projects, to manage the
   :doc:`network stack </developer/system/networking>`, :doc:`the firewall </user/security-in-qubes/firewall>`, or to fulfill other
@@ -20,7 +25,7 @@ These qubes, which are implemented as :ref:`virtual machines (VMs)<user/referenc
   :doc:`stripped-down </introduction/getting-started/>` virtual machines based on popular operating systems,
   such as :doc:`Fedora </user/templates/fedora/fedora>`, :doc:`Debian </user/templates/debian/debian>`, and
   `Windows <https://github.com/Qubes-Community/Contents/blob/master/docs/os/windows/windows.md>`__.
-
+               
 - **Levels of trust:** from complete to non-existent. All windows are displayed in a unified desktop environment with
   :doc:`unforgeable colored window borders </introduction/getting-started>` so that different security levels are easily identifiable.
 
@@ -39,7 +44,7 @@ Features
 - **Strong isolation** Isolate different pieces of software as if they were installed on separate
   physical machines using advanced virtualization techniques.
 
-- **Template system** Use :ref:`app qubes <user/reference/glossary:app qube>` to
+- **Template system** Use :term:`app qubes  <app qube>` to
   share a root file system without sacrificing security using the innovative
   :doc:`Template system </user/templates/templates>`.
 
@@ -47,7 +52,7 @@ Features
 - **Multiple operating systems** Use multiple operating systems at the same time, including
   :doc:`Fedora </user/templates/fedora/fedora>`, :doc:`Debian </user/templates/debian/debian/>`, and
   `Windows <https://github.com/Qubes-Community/Contents/blob/master/docs/os/windows/windows.md>`__
-
+         
 - **Disposables** Create :doc:`disposables </user/how-to-guides/how-to-use-disposables>` on the fly that self-destruct when shut down.
 
 - **Whonix integration** Run `Tor <https://www.torproject.org/>`__ securely system-wide using `Whonix with Qubes <https://www.whonix.org/wiki/Qubes>`__.
@@ -137,7 +142,7 @@ plug in devices, and install software free from worry. It's a place where
 **you** have control over your software, not the other way around.
 (See some :doc:`examples of how different types of users organize their qubes </user/how-to-guides/how-to-organize-your-qubes>`.)
 
-Qubes is also powerful. Organizations like the `Freedom of the Press Foundation <https://securedrop.org/news/piloting-securedrop-workstation-qubes-os>`__,
+Qubes is also powerful. Organizations like the `Freedom of the Press Foundation <https://securedrop.org/news/piloting-securedrop-workstation-qubes-os>`__, 
 `Mullvad <https://twitter.com/mullvadnet/status/631010362083643392>`__,
 and `Let's Encrypt <https://twitter.com/letsencrypt/status/1239934557710737410>`__
 rely on Qubes as they build and maintain critical privacy and
@@ -187,7 +192,7 @@ presentation.
 
 
 - If you’re a current or potential Qubes user, you may want to check out the :doc:`documentation </index>` and the :ref:`user FAQ <introduction/faq:users>`.
-- If you’re a developer, there’s dedicated :ref:`developer documentation <index:developer documentation>` and a :ref:`developer FAQ <introduction/faq:developers>` just for you.
-- Ready to give Qubes a try? Head on over to the `downloads page <https://www.qubes-os.org/downloads/>`__, and read the :doc:`installation guide </user/downloading-installing-upgrading/installation-guide>`.
+- If you’re a developer, there’s dedicated :ref:`index:Developer Documentation` and a :ref:`developer FAQ <introduction/faq:developers>` just for you.
+- Ready to give Qubes a try? Head on over to the `downloads page <https://www.qubes-os.org/downloads/>`__, and read the :ref:`Installation guide`.
 - Need help, or just want to join the conversation? Learn more about :doc:`help, support, the mailing lists, and the forum </introduction/support>`.