Refactor links in order to obey the new convention rule

user/advanced-configuration/bind-dirs.md

@@ -21,7 +21,7 @@ In a TemplateBasedVM all of the file system comes from the template except `/hom
 This means that changes in the rest of the filesystem are lost when the TemplateBasedVM is shutdown.
 bind-dirs provides a mechanism whereby files usually taken from the template can be persisted across reboots.
 
-For example, in Whonix, [Tor's data dir `/var/lib/tor` has been made persistent in the TemplateBased ProxyVM sys-whonix][whonix]
+For example, in Whonix, [Tor's data dir `/var/lib/tor` has been made persistent in the TemplateBased ProxyVM sys-whonix](https://github.com/Whonix/qubes-whonix/blob/8438d13d75822e9ea800b9eb6024063f476636ff/usr/lib/qubes-bind-dirs.d/40_qubes-whonix.conf#L5)
 In this way sys-whonix can benefit from the Tor anonymity feature 'persistent Tor entry guards' but does not have to be a StandaloneVM.
 
 ## How to use bind-dirs.sh? ##
@@ -85,7 +85,7 @@ Note that you must create the full folder structure under `/rw/bind-dirs` - e.g
 Any changes you make will not survive a reboot. If you think it likely you will want to edit a file, then either include the parent directory in bind-dirs rather than the file, or perform the file operation on the file in `/rw/bind-dirs`.
 * Some files are altered when a qube boots - e.g. `/etc/hosts`.
 If you try to use bind-dirs on such files you may break your qube in unpredictable ways.
-You can add persistent rules to `/etc/hosts` using [`/rw/config/rc.local`][config-file]
+You can add persistent rules to `/etc/hosts` using [`/rw/config/rc.local`](/doc/config-files)
 
 ## How to remove binds from bind-dirs.sh? ##
 
@@ -105,5 +105,3 @@ binds=( "${binds[@]/'/var/lib/tor'}" )
 
 [TemplateBasedVMs: make selected files and folders located in the root image persistent- review bind-dirs.sh](https://groups.google.com/forum/#!topic/qubes-devel/tcYQ4eV-XX4/discussion)
 
-[config-file]: /doc/config-files
-[whonix]: https://github.com/Whonix/qubes-whonix/blob/8438d13d75822e9ea800b9eb6024063f476636ff/usr/lib/qubes-bind-dirs.d/40_qubes-whonix.conf#L5

user/advanced-configuration/installing-contributed-packages.md

@@ -9,14 +9,14 @@ title: Installing contributed packages
 # Installing contributed packages
 
 _This page is for users who wish to install contributed packages.
-If you want to contribute a package, please see [package contributions]._
+If you want to contribute a package, please see [package contributions](/doc/package-contributions/)._
 
-Qubes OS contributed packages are available under the [QubesOS-contrib] GitHub Project.
-This is a place where our community can [contribute Qubes OS related packages, additions and various customizations][package contributions].
+Qubes OS contributed packages are available under the [QubesOS-contrib](https://github.com/QubesOS-contrib/) GitHub Project.
+This is a place where our community can [contribute Qubes OS related packages, additions and various customizations](/doc/package-contributions/).
 
 ## Installing the repositories
 
-If you want to install one of these packages, first you need to enable the repository in your system (dom0 and/or templates). This can be done by installing the `qubes-repo-contrib` package. This package includes the repository definition and keys necessary to download, verify, and install [QubesOS-contrib] packages.
+If you want to install one of these packages, first you need to enable the repository in your system (dom0 and/or templates). This can be done by installing the `qubes-repo-contrib` package. This package includes the repository definition and keys necessary to download, verify, and install [QubesOS-contrib](https://github.com/QubesOS-contrib/) packages.
 
 In dom0, use `qubes-dom0-update`:
 
@@ -57,5 +57,3 @@ sudo qubes-dom0-update --clean qvm-screenshot-tool
 
 Please see the package's README for specific installation and setup instructions.
 
-[package contributions]: /doc/package-contributions/
-[QubesOS-contrib]: https://github.com/QubesOS-contrib/

user/advanced-configuration/managing-vm-kernel.md

@@ -11,7 +11,7 @@ title: Managing VM kernel
 # VM kernel managed by dom0
 
 By default, VMs kernels are provided by dom0.
-(See [here][dom0-kernel-upgrade] for information about upgrading kernels in dom0.)
+(See [here](/doc/software-update-dom0/#kernel-upgrade) for information about upgrading kernels in dom0.)
 This means that:
 
 1. You can select the kernel version (using GUI VM Settings tool or `qvm-prefs` commandline tool);
@@ -363,4 +363,3 @@ update-initramfs: Generating /boot/initrd.img-3.16.0-4-amd64
 
 In case of problems, visit the [VM Troubleshooting guide](/doc/vm-troubleshooting/#vm-kernel-troubleshooting) to learn how to access the VM console, view logs and fix a VM kernel installation.
 
-[dom0-kernel-upgrade]: /doc/software-update-dom0/#kernel-upgrade

user/advanced-configuration/resize-disk-image.md

@@ -106,6 +106,5 @@ qvm-shutdown qube1
 sudo lvresize --size 1024M /dev/qubes_dom0/vm-qube1-private
 ```
 
-If you have a SSD see [here][fstrim] for information on using fstrim.
+If you have a SSD see [here](/doc/disk-trim) for information on using fstrim.
 
-[fstrim]: /doc/disk-trim

user/advanced-configuration/rpc-policy.md

@@ -10,7 +10,7 @@ RPC Policies
 ============
 
 This document explains the basics of RPC policies in Qubes.
-For more information, see [Qrexec: command execution in VMs][qrexec3].
+For more information, see [Qrexec: command execution in VMs](/doc/qrexec3/).
 
 Here's an example of an RPC policy file in dom0:
 
@@ -54,9 +54,8 @@ Therefore, parsing will always stop at this rule, and no rules below it will eve
 All together, the three rules we added say that all VMs tagged with "work" are allowed to copy files to each other; however, they're denied from copying files to other VMs (without the "work" tag), and other VMs (without the "work" tag) are denied from copying files to them.
 The fourth rule means that the user gets prompted for any situation not already covered.
 
-Further details about how this system works can be found in [Qrexec: command execution in VMs][qrexec3].
+Further details about how this system works can be found in [Qrexec: command execution in VMs](/doc/qrexec3/).
 
 (***Note**: the `$` character is deprecated in qrexec keywords -- please use `@` instead (e.g. `@anyvm`).
 For more information, see the bulletin [here](https://github.com/QubesOS/qubes-secpack/blob/master/QSBs/qsb-038-2018.txt).*)
 
-[qrexec3]: /doc/qrexec3/

user/advanced-configuration/salt.md

@@ -22,7 +22,7 @@ In the current form the **API is provisional** and subject to change between
 This document is not meant to be comprehensive Salt documentation; however,
 before writing anything it is required you have at least *some* understanding of
 basic Salt-related vocabulary.
-For more exhaustive documentation, visit [official site][salt-doc], though we
+For more exhaustive documentation, visit [official site](https://docs.saltstack.com/en/latest/), though we
 must warn you that it is not easy to read if you just start working with Salt
 and know nothing.
 
@@ -86,17 +86,17 @@ It executes a command on behalf of the administrator.
 `name: echo 'hello world'` is a parameter for the execution module `cmd.run`.
 The module used defines which parameters can be passed to it.
 
-There is a list of [officially available states][salt-doc-states].
+There is a list of [officially available states](https://docs.saltstack.com/en/latest/ref/states/all/).
 There are many very useful states:
 
-- For [managing files][salt-doc-states-file]: Use this to create files or
+- For [managing files](https://docs.saltstack.com/en/latest/ref/states/all/salt.states.file.html): Use this to create files or
   directories and change them (append lines, replace text, set their content etc.)
-- For [installing and uninstalling][salt-doc-states-pkg] packages.
-- For [executing shell commands][salt-doc-states-cmd].
+- For [installing and uninstalling](https://docs.saltstack.com/en/latest/ref/states/all/salt.states.pkg.html) packages.
+- For [executing shell commands](https://docs.saltstack.com/en/latest/ref/states/all/salt.states.file.html).
 
 With these three states you can define most of the configuration of a VM.
 
-You can also [order the execution][salt-doc-states-order] of your states:
+You can also [order the execution](https://docs.saltstack.com/en/latest/ref/states/ordering.html) of your states:
 
 ```
 D:
@@ -121,7 +121,7 @@ A:
 
 The order of execution will be `A, B, C, D`.
 The official documentation has more details on the
-[require][salt-doc-states-req] and [order][salt-doc-states-ord] arguments.
+[require](https://docs.saltstack.com/en/latest/ref/states/requisites.html) and [order](https://docs.saltstack.com/en/latest/ref/states/ordering.html#the-order-option) arguments.
 
 #### State Files
 
@@ -133,7 +133,7 @@ configuration (e.g., a state file `mail.sls` could setup a VM for e-mail).
 #### Top Files
 
 After you have several state files, you need something to assign them to a VM.
-This is done by `*.top` files ([official documentation][salt-doc-top]).
+This is done by `*.top` files ([official documentation](https://docs.saltstack.com/en/latest/ref/states/top.html)).
 Their structure looks like this:
 
 ```
@@ -195,15 +195,15 @@ $ qubesctl --all state.highstate
 
 You will sometimes find yourself writing repetitive states.
 To solve this, there is the ability to template files or states.
-This is most commonly done with [Jinja][jinja].
+This is most commonly done with [Jinja](http://jinja.pocoo.org/).
 Jinja is similar to Python and in many cases behaves in a similar fashion, but
 there are sometimes differences when, for example, you set some variable inside
 a loop: the variable outside will not get changed.
 Instead, to get this behavior, you would use a `do` statement.
-So you should take a look at the [Jinja API documentation][jinja-tmp].
+So you should take a look at the [Jinja API documentation](http://jinja.pocoo.org/docs/2.9/templates/).
 Documentation about using Jinja to directly call Salt functions and get data
 about your system can be found in the official
-[Salt documentation][jinja-call-salt-functions].
+[Salt documentation](https://docs.saltstack.com/en/getstarted/config/jinja.html#get-data-using-salt).
 
 ## Salt Configuration, QubesOS layout
 
@@ -259,7 +259,7 @@ This way dom0 doesn't directly interact with potentially malicious target VMs;
 and in the case of a compromised Salt VM, because they are temporary, the
 compromise cannot spread from one VM to another.
 
-Beginning with Qubes 4.0 and after [QSB #45], we implemented two changes:
+Beginning with Qubes 4.0 and after [QSB #45](/news/2018/12/03/qsb-45/), we implemented two changes:
 
 1. Added the `management_dispvm` VM property, which specifies the DVM
    Template that should be used for management, such as Salt
@@ -599,26 +599,11 @@ install template and shutdown updateVM:
 
 ## Further Reading
 
-- [Salt documentation][salt-doc]
-- [Salt states][salt-doc-states] ([files][salt-doc-states-file], [commands][salt-doc-states-cmd],
-  [packages][salt-doc-states-pkg], [ordering][salt-doc-states-order])
-- [Top files][salt-doc-top]
-- [Jinja templates][jinja]
-- [Qubes specific modules][salt-qvm-doc]
-- [Formulas for default Qubes VMs][salt-virtual-machines-states]
+- [Salt documentation](https://docs.saltstack.com/en/latest/)
+- [Salt states](https://docs.saltstack.com/en/latest/ref/states/all/) ([files](https://docs.saltstack.com/en/latest/ref/states/all/salt.states.file.html), [commands](https://docs.saltstack.com/en/latest/ref/states/all/salt.states.file.html),
+  [packages](https://docs.saltstack.com/en/latest/ref/states/all/salt.states.pkg.html), [ordering](https://docs.saltstack.com/en/latest/ref/states/ordering.html))
+- [Top files](https://docs.saltstack.com/en/latest/ref/states/top.html)
+- [Jinja templates](http://jinja.pocoo.org/)
+- [Qubes specific modules](https://github.com/QubesOS/qubes-mgmt-salt-dom0-qvm/blob/master/README.rst)
+- [Formulas for default Qubes VMs](https://github.com/QubesOS/qubes-mgmt-salt-dom0-virtual-machines/tree/master/qvm)
 
-[salt-doc]: https://docs.saltstack.com/en/latest/
-[salt-qvm-doc]: https://github.com/QubesOS/qubes-mgmt-salt-dom0-qvm/blob/master/README.rst
-[salt-virtual-machines-states]: https://github.com/QubesOS/qubes-mgmt-salt-dom0-virtual-machines/tree/master/qvm
-[salt-doc-states]: https://docs.saltstack.com/en/latest/ref/states/all/
-[salt-doc-states-file]: https://docs.saltstack.com/en/latest/ref/states/all/salt.states.file.html
-[salt-doc-states-pkg]: https://docs.saltstack.com/en/latest/ref/states/all/salt.states.pkg.html
-[salt-doc-states-cmd]: https://docs.saltstack.com/en/latest/ref/states/all/salt.states.file.html
-[salt-doc-states-order]: https://docs.saltstack.com/en/latest/ref/states/ordering.html
-[salt-doc-states-req]: https://docs.saltstack.com/en/latest/ref/states/requisites.html
-[salt-doc-states-ord]: https://docs.saltstack.com/en/latest/ref/states/ordering.html#the-order-option
-[salt-doc-top]:https://docs.saltstack.com/en/latest/ref/states/top.html
-[jinja]: http://jinja.pocoo.org/
-[jinja-tmp]: http://jinja.pocoo.org/docs/2.9/templates/
-[jinja-call-salt-functions]: https://docs.saltstack.com/en/getstarted/config/jinja.html#get-data-using-salt
-[QSB #45]: /news/2018/12/03/qsb-45/

user/advanced-configuration/secondary-storage.md

@@ -114,5 +114,3 @@ By default VMs will be created on the main Qubes disk (i.e. a small SSD), to cre
 qvm-create -P poolhd0_qubes --label red unstrusted-hdd
 ```
 
-[Qubes Backup]: /doc/BackupRestore/
-[TemplateVM]: /doc/Templates/

user/advanced-configuration/usb-qubes.md

@@ -14,20 +14,20 @@ title: USB Qubes
 
 # USB Qubes #
 
-If during installation you enabled the creation of a USB-qube, your system should be setup already and none of the mentioned steps here should be necessary. (Unless you want to [remove your USB-qube].) If for any reason no USB-qube was created during installation, this guide will show you how to do so.
+If during installation you enabled the creation of a USB-qube, your system should be setup already and none of the mentioned steps here should be necessary. (Unless you want to [remove your USB-qube](#removing-a-usb-qube).) If for any reason no USB-qube was created during installation, this guide will show you how to do so.
 
-**Caution:** If you want to use a USB-keyboard, please beware of the possibility to lock yourself out! To avoid this problem [enable your keyboard for login]!
+**Caution:** If you want to use a USB-keyboard, please beware of the possibility to lock yourself out! To avoid this problem [enable your keyboard for login](#enable-a-usb-keyboard-for-login)!
 
 ## Creating and Using a USB qube ##
 
 **Warning:** This has the potential to prevent you from connecting a keyboard to Qubes via USB.
 There are problems with doing this in an encrypted install (LUKS).
-If you find yourself in this situation, see this [issue][2270-comm23].
+If you find yourself in this situation, see this [issue](https://github.com/QubesOS/qubes-issues/issues/2270#issuecomment-242900312).
 
-A USB qube acts as a secure handler for potentially malicious USB devices, preventing them from coming into contact with dom0 (which could otherwise be fatal to the security of the whole system). It thereby mitigates some of the [security implications] of using USB devices.
+A USB qube acts as a secure handler for potentially malicious USB devices, preventing them from coming into contact with dom0 (which could otherwise be fatal to the security of the whole system). It thereby mitigates some of the [security implications](/doc/device-handling-security/#usb-security) of using USB devices.
 With a USB qube, every time you connect an untrusted USB drive to a USB port managed by that USB controller, you will have to attach it to the qube in which you wish to use it (if different from the USB qube itself), either by using Qubes VM Manager or the command line (see instructions above).
-The USB controller may be assigned on the **Devices** tab of a qube's settings page in Qubes VM Manager or by using the [qvm-pci][PCI Devices] command.
-For guidance on finding the correct USB controller, see the [according passage on PCI-devices][usb-controller].
+The USB controller may be assigned on the **Devices** tab of a qube's settings page in Qubes VM Manager or by using the [qvm-pci](/doc/pci-devices/) command.
+For guidance on finding the correct USB controller, see the [according passage on PCI-devices](/doc/usb-devices/#finding-the-right-usb-controller).
 You can create a USB qube using the management stack by performing the following steps as root in dom0:
 
 ```
@@ -36,7 +36,7 @@ sudo qubesctl state.sls qvm.sys-usb
 
 Alternatively, you can create a USB qube manually as follows:
 
-1. Read the [PCI Devices] page to learn how to list and identify your USB controllers.
+1. Read the [PCI Devices](/doc/pci-devices/) page to learn how to list and identify your USB controllers.
    Carefully check whether you have a USB controller that would be appropriate to assign to a USB qube.
    Note that it should be free of input devices, programmable devices, and any other devices that must be directly available to dom0.
    If you find a free controller, note its name and proceed to step 2.
@@ -54,19 +54,19 @@ Alternatively, you can create a USB qube manually as follows:
 5. Recommended: Check the box on the "Basic" tab which says "Start VM automatically on boot".
    (This will help to mitigate attacks in which someone forces your system to reboot, then plugs in a malicious USB device.)
 
-If the USB qube will not start, please have a look at the [faq].
+If the USB qube will not start, please have a look at the [faq](/faq/#i-created-a-usbvm-and-assigned-usb-controllers-to-it-now-the-usbvm-wont-boot).
 
 ## Enable a USB keyboard for login ##
 
-**Caution:** Please carefully read the [Security Warning about USB Input Devices] before proceeding!
+**Caution:** Please carefully read the [Security Warning about USB Input Devices](/doc/device-handling-security/#security-warning-on-usb-input-devices) before proceeding!
 
 If you use USB keyboard, automatic USB qube creation during installation is disabled.
 Additional steps are required to avoid locking you out from the system.
-Those steps are not performed by default, because of risk explained in [Security Warning about USB Input Devices].
+Those steps are not performed by default, because of risk explained in [Security Warning about USB Input Devices](/doc/device-handling-security/#security-warning-on-usb-input-devices).
 
 ### Automatic setup ###
 
-To allow USB keyboard usage (including early boot for LUKS passphrase), make sure you have the latest `qubes-mgmt-salt-dom0-virtual-machines` package (simply [install dom0 updates]) and execute in dom0:
+To allow USB keyboard usage (including early boot for LUKS passphrase), make sure you have the latest `qubes-mgmt-salt-dom0-virtual-machines` package (simply [install dom0 updates](/doc/software-update-dom0/#how-to-update-dom0)) and execute in dom0:
 
 ```
 sudo qubesctl state.sls qvm.usb-keyboard
@@ -76,7 +76,7 @@ The above command will take care of all required configuration, including creati
 Note that it will expose dom0 to USB devices while entering LUKS passphrase.
 Users are advised to physically disconnect other devices from the system for that time, to minimize the risk.
 
-To undo these changes, please follow the section on [**Removing a USB qube**][remove your USB-qube]!
+To undo these changes, please follow the section on [**Removing a USB qube**](#removing-a-usb-qube)!
 
 If you wish to perform only a subset of this configuration (for example do not enable USB keyboard during boot), see manual instructions below.
 
@@ -107,12 +107,12 @@ sys-usb dom0 ask,default_target=dom0
 
 *Don't do that if you want to unlock your device with a USB keyboard!*
 
-Additionally, if you want to use USB keyboard to enter LUKS passphrase, it is incompatible with [hiding USB controllers from dom0].
+Additionally, if you want to use USB keyboard to enter LUKS passphrase, it is incompatible with [hiding USB controllers from dom0](#how-to-hide-all-usb-controllers-from-dom0).
 You need to revert that procedure (remove `rd.qubes.hide_all_usb` option from files mentioned there) and employ alternative protection during system boot - disconnect other devices during startup.
 
 ## Auto Enabling A USB Mouse ##
 
-**Caution:** Please carefully read the [Security Warning about USB Input Devices] before proceeding.
+**Caution:** Please carefully read the [Security Warning about USB Input Devices](/doc/device-handling-security/#security-warning-on-usb-input-devices) before proceeding.
 
 Handling a USB mouse isn't as critical as handling a keyboard, since you can login using the keyboard and accept the popup dialogue using your keyboard alone.
 
@@ -141,7 +141,7 @@ sys-usb dom0 allow
 ## How to hide all USB controllers from dom0 ##
 
 (Note: `rd.qubes.hide_all_usb` is set automatically if you opt to create a USB qube during installation.
-This also occurs automatically if you choose to [create a USB qube] using the `qubesctl` method, which is the
+This also occurs automatically if you choose to [create a USB qube](#creating-and-using-a-usb-qube) using the `qubesctl` method, which is the
 first pair of steps in the linked section.)
 
 **Warning:** A USB keyboard cannot be used to type the disk passphrase if USB controllers were hidden from dom0.
@@ -155,7 +155,7 @@ There are two approaches to this problem:
 1. Physically disconnect all USB devices whenever you reboot the host.
 2. Hide (i.e., blacklist) all USB controllers from dom0.
 
-**Warning:** If you use a USB [AEM] device, do not use the second option.
+**Warning:** If you use a USB [AEM](/doc/anti-evil-maid/) device, do not use the second option.
 Using a USB AEM device requires dom0 to have access to the USB controller to which your USB AEM device is attached.
 If dom0 cannot read your USB AEM device, AEM will hang.
 
@@ -203,15 +203,3 @@ The procedure to hide all USB controllers from dom0 is as follows:
   6. Save and close the file.
   7. Reboot.
 
-[remove your USB-qube]: #removing-a-usb-qube
-[security implications]: /doc/device-handling-security/#usb-security
-[enable your keyboard for login]: #enable-a-usb-keyboard-for-login
-[2270-comm23]: https://github.com/QubesOS/qubes-issues/issues/2270#issuecomment-242900312
-[PCI Devices]: /doc/pci-devices/
-[usb-controller]: /doc/usb-devices/#finding-the-right-usb-controller
-[faq]: /faq/#i-created-a-usbvm-and-assigned-usb-controllers-to-it-now-the-usbvm-wont-boot
-[Security Warning about USB Input Devices]: /doc/device-handling-security/#security-warning-on-usb-input-devices
-[install dom0 updates]: /doc/software-update-dom0/#how-to-update-dom0
-[hiding USB controllers from dom0]: #how-to-hide-all-usb-controllers-from-dom0
-[AEM]: /doc/anti-evil-maid/
-[create a USB qube]: #creating-and-using-a-usb-qube