Reformat docs with mdformat

docs/about/faq.md

@@ -50,8 +50,8 @@ we have a "docker-issues" channel where you can ask for Docker-specific help to
 ## What is the recommended update path? Can I skip multiple versions while updating?
 
 Please follow the steps outlined in the [upgrade guide](../setup/upgrade.md) to update your existing Headscale
-installation. Its required to update from one stable version to the next (e.g. 0.26.0 → 0.27.1 → 0.28.0)
+installation. Its required to update from one stable version to the next (e.g. 0.26.0 → 0.27.1 → 0.28.0) without
-without skipping minor versions in between. You should always pick the latest available patch release.
+skipping minor versions in between. You should always pick the latest available patch release.
 
 Be sure to check the [changelog](https://github.com/juanfont/headscale/blob/main/CHANGELOG.md) for version specific
 upgrade instructions and breaking changes.
@@ -76,7 +76,7 @@ of Headscale:
     - they rarely "move" (change their endpoints)
     - new nodes are added rarely
 
-2. An environment with 80 laptops/phones (end user devices)
+1. An environment with 80 laptops/phones (end user devices)
 
     - nodes move often, e.g. switching from home to office
 
@@ -142,8 +142,8 @@ connect back to the administrator's node. Why do all nodes see the administrator
 `tailscale status`?
 
 This is essentially how Tailscale works. If traffic is allowed to flow in one direction, then both nodes see each other
-in their output of `tailscale status`. Traffic is still filtered according to the ACL, with the exception of `tailscale
+in their output of `tailscale status`. Traffic is still filtered according to the ACL, with the exception of
-ping` which is always allowed in either direction.
+`tailscale ping` which is always allowed in either direction.
 
 See also <https://tailscale.com/kb/1087/device-visibility>.
 
@@ -160,8 +160,8 @@ indicates which part of the policy is invalid. Follow these steps to fix your po
 !!! warning "Full server configuration required"
 
     The above commands to get/set the policy require a complete server configuration file including database settings. A
-    minimal config to [control Headscale via remote CLI](../ref/api.md#grpc) is not sufficient. You may use `headscale
+    minimal config to [control Headscale via remote CLI](../ref/api.md#grpc) is not sufficient. You may use
-    -c /path/to/config.yaml` to specify the path to an alternative configuration file.
+    `headscale -c /path/to/config.yaml` to specify the path to an alternative configuration file.
 
 ## How can I migrate back to the recommended IP prefixes?
 

docs/about/features.md

@@ -29,7 +29,7 @@ provides on overview of Headscale's feature and compatibility with the Tailscale
       routers](../ref/routes.md#automatically-approve-routes-of-a-subnet-router) and [exit
       nodes](../ref/routes.md#automatically-approve-an-exit-node-with-auto-approvers)
     - [x] [Tailscale SSH](https://tailscale.com/kb/1193/tailscale-ssh)
-* [x] [Node registration using Single-Sign-On (OpenID Connect)](../ref/oidc.md) ([GitHub label "OIDC"](https://github.com/juanfont/headscale/labels/OIDC))
+- [x] [Node registration using Single-Sign-On (OpenID Connect)](../ref/oidc.md) ([GitHub label "OIDC"](https://github.com/juanfont/headscale/labels/OIDC))
     - [x] Basic registration
     - [x] Update user profile from identity provider
     - [ ] OIDC groups cannot be used in ACLs

docs/ref/acls.md

@@ -257,9 +257,11 @@ Includes devices where the same user is authenticated on both the source and des
   "dst": ["autogroup:self:*"]
 }
 ```
+
 *Using `autogroup:self` may cause performance degradation on the Headscale coordinator server in large deployments, as filter rules must be compiled per-node rather than globally and the current implementation is not very efficient.*
 
 If you experience performance issues, consider using more specific ACL rules or limiting the use of `autogroup:self`.
+
 ```json
 {
   // The following rules allow internal users to communicate with their

docs/ref/api.md

@@ -1,4 +1,5 @@
 # API
+
 Headscale provides a [HTTP REST API](#rest-api) and a [gRPC interface](#grpc) which may be used to integrate a [web
 interface](integration/web-ui.md), [remote control Headscale](#setup-remote-control) or provide a base for custom
 integration and tooling.
@@ -30,8 +31,7 @@ headscale apikeys expire --prefix <PREFIX>
 - API endpoint: `/api/v1`, e.g. `https://headscale.example.com/api/v1`
 - Documentation: `/swagger`, e.g. `https://headscale.example.com/swagger`
 - Headscale Version: `/version`, e.g. `https://headscale.example.com/version`
-- Authenticate using HTTP Bearer authentication by sending the [API key](#api) with the HTTP `Authorization: Bearer
+- Authenticate using HTTP Bearer authentication by sending the [API key](#api) with the HTTP `Authorization: Bearer <API_KEY>` header.
-  <API_KEY>` header.
 
 Start by [creating an API key](#api) and test it with the examples below. Read the API documentation provided by your
 Headscale server at `/swagger` for details.

docs/ref/configuration.md

@@ -17,8 +17,8 @@
 
     === "View on GitHub"
 
-        * Development version: <https://github.com/juanfont/headscale/blob/main/config-example.yaml>
+        - Development version: <https://github.com/juanfont/headscale/blob/main/config-example.yaml>
-        * Version {{ headscale.version }}: <https://github.com/juanfont/headscale/blob/v{{ headscale.version }}/config-example.yaml>
+        - Version {{ headscale.version }}: https://github.com/juanfont/headscale/blob/v{{ headscale.version }}/config-example.yaml
 
     === "Download with `wget`"
 

docs/ref/derp.md

@@ -165,11 +165,10 @@ Any Tailscale client may be used to introspect the DERP map and to check for con
 Additional DERP related metrics and information is available via the [metrics and debug
 endpoint](./debug.md#metrics-and-debug-endpoint).
 
-[^1]:
-    This assumes that the default region code of the [configuration file](./configuration.md) is used.
-
 ## Limitations
 
 - The embedded DERP server can't be used for Tailscale's captive portal checks as it doesn't support the `/generate_204`
   endpoint via HTTP on port tcp/80.
 - There are no speed or throughput optimisations, the main purpose is to assist in node connectivity.
+
+[^1]: This assumes that the default region code of the [configuration file](./configuration.md) is used.

docs/ref/dns.md

@@ -66,9 +66,9 @@ hostname and port combination "http://hostname-in-magic-dns.myvpn.example.com:30
 
         !!! tip "Good to know"
 
-            * The `dns.extra_records_path` option in the [configuration file](./configuration.md) needs to reference the
+            - The `dns.extra_records_path` option in the [configuration file](./configuration.md) needs to reference the
               JSON file containing extra DNS records.
-            * Be sure to "sort keys" and produce a stable output in case you generate the JSON file with a script.
+            - Be sure to "sort keys" and produce a stable output in case you generate the JSON file with a script.
               Headscale uses a checksum to detect changes to the file and a stable output avoids unnecessary processing.
 
 1. Verify that DNS records are properly set using the DNS querying tool of your choice:

docs/ref/oidc.md

@@ -40,9 +40,9 @@ A basic configuration connects Headscale to an identity provider and typically r
 
 === "Identity provider"
 
-    * Create a new confidential client (`Client ID`, `Client secret`)
+    - Create a new confidential client (`Client ID`, `Client secret`)
-    * Add Headscale's OIDC callback URL as valid redirect URL: `https://headscale.example.com/oidc/callback`
+    - Add Headscale's OIDC callback URL as valid redirect URL: `https://headscale.example.com/oidc/callback`
-    * Configure additional parameters to improve user experience such as: name, description, logo, …
+    - Configure additional parameters to improve user experience such as: name, description, logo, …
 
 ### Enable PKCE (recommended)
 
@@ -63,8 +63,8 @@ recommended and needs to be configured for Headscale and the identity provider a
 
 === "Identity provider"
 
-    * Enable PKCE for the headscale client
+    - Enable PKCE for the headscale client
-    * Set the PKCE challenge method to "S256"
+    - Set the PKCE challenge method to "S256"
 
 ### Authorize users with filters
 
@@ -75,11 +75,11 @@ are configured, a user needs to pass all of them.
 
 === "Allowed domains"
 
-    * Check the email domain of each authenticating user against the list of allowed domains and only authorize users
+    - Check the email domain of each authenticating user against the list of allowed domains and only authorize users
       whose email domain matches `example.com`.
-    * A verified email address is required [unless email verification is disabled](#control-email-verification).
+    - A verified email address is required [unless email verification is disabled](#control-email-verification).
-    * Access allowed: `alice@example.com`
+    - Access allowed: `alice@example.com`
-    * Access denied: `bob@example.net`
+    - Access denied: `bob@example.net`
 
     ```yaml hl_lines="5-6"
     oidc:
@@ -92,11 +92,11 @@ are configured, a user needs to pass all of them.
 
 === "Allowed users/emails"
 
-    * Check the email address of each authenticating user against the list of allowed email addresses and only authorize
+    - Check the email address of each authenticating user against the list of allowed email addresses and only authorize
       users whose email is part of the `allowed_users` list.
-    * A verified email address is required [unless email verification is disabled](#control-email-verification).
+    - A verified email address is required [unless email verification is disabled](#control-email-verification).
-    * Access allowed: `alice@example.com`, `bob@example.net`
+    - Access allowed: `alice@example.com`, `bob@example.net`
-    * Access denied: `mallory@example.net`
+    - Access denied: `mallory@example.net`
 
     ```yaml hl_lines="5-7"
     oidc:
@@ -110,10 +110,10 @@ are configured, a user needs to pass all of them.
 
 === "Allowed groups"
 
-    * Use the OIDC `groups` claim of each authenticating user to get their group membership and only authorize users
+    - Use the OIDC `groups` claim of each authenticating user to get their group membership and only authorize users
       which are members in at least one of the referenced groups.
-    * Access allowed: users in the `headscale_users` group
+    - Access allowed: users in the `headscale_users` group
-    * Access denied: users without groups, users with other groups
+    - Access denied: users without groups, users with other groups
 
     ```yaml hl_lines="5-7"
     oidc:
@@ -163,7 +163,6 @@ Access Token.
     Please keep in mind that the Access Token is typically a short-lived token that expires within a few minutes. You
     will have to configure token expiration in your identity provider to avoid frequent re-authentication.
 
-
     ```yaml hl_lines="5"
     oidc:
       issuer: "https://sso.example.com"
@@ -175,6 +174,7 @@ Access Token.
 !!! tip "Expire a node and force re-authentication"
 
     A node can be expired immediately via:
+
     ```console
     headscale node expire -i <NODE_ID>
     ```
@@ -303,15 +303,15 @@ Console.
 #### Steps
 
 1. Go to [Google Console](https://console.cloud.google.com) and login or create an account if you don't have one.
-2. Create a project (if you don't already have one).
+1. Create a project (if you don't already have one).
-3. On the left hand menu, go to `APIs and services` -> `Credentials`
+1. On the left hand menu, go to `APIs and services` -> `Credentials`
-4. Click `Create Credentials` -> `OAuth client ID`
+1. Click `Create Credentials` -> `OAuth client ID`
-5. Under `Application Type`, choose `Web Application`
+1. Under `Application Type`, choose `Web Application`
-6. For `Name`, enter whatever you like
+1. For `Name`, enter whatever you like
-7. Under `Authorised redirect URIs`, add Headscale's OIDC callback URL: `https://headscale.example.com/oidc/callback`
+1. Under `Authorised redirect URIs`, add Headscale's OIDC callback URL: `https://headscale.example.com/oidc/callback`
-8. Click `Save` at the bottom of the form
+1. Click `Save` at the bottom of the form
-9. Take note of the `Client ID` and `Client secret`, you can also download it for reference if you need it.
+1. Take note of the `Client ID` and `Client secret`, you can also download it for reference if you need it.
-10. [Configure Headscale following the "Basic configuration" steps](#basic-configuration). The issuer URL for Google
+1. [Configure Headscale following the "Basic configuration" steps](#basic-configuration). The issuer URL for Google
    OAuth is: `https://accounts.google.com`.
 
 ### Kanidm

docs/ref/registration.md

@@ -136,6 +136,6 @@ Its best suited for automation.
     tailscale up --login-server <YOUR_HEADSCALE_URL> --authkey <YOUR_AUTH_KEY>
     ```
 
-    The registration of a tagged node is complete and it should be listed as "online" in the output of `headscale nodes
+    The registration of a tagged node is complete and it should be listed as "online" in the output of
-    list`. The "User" column displays `tagged-devices` as the owner of the node. See the "Tags" column for the list of
+    `headscale nodes list`. The "User" column displays `tagged-devices` as the owner of the node. See the "Tags" column for the list of
     assigned tags.

docs/ref/tls.md

@@ -50,7 +50,7 @@ Headscale uses [autocert](https://pkg.go.dev/golang.org/x/crypto/acme/autocert),
 If you want to validate that certificate renewal completed successfully, this can be done either manually, or through external monitoring software. Two examples of doing this manually:
 
 1. Open the URL for your headscale server in your browser of choice, and manually inspecting the expiry date of the certificate you receive.
-2. Or, check remotely from CLI using `openssl`:
+1. Or, check remotely from CLI using `openssl`:
 
 ```console
 $ openssl s_client -servername [hostname] -connect [hostname]:443 | openssl x509 -noout -dates

docs/setup/requirements.md

@@ -46,7 +46,6 @@ The headscale documentation and the provided examples are written with a few ass
 
 Please adjust to your local environment accordingly.
 
-[^1]:
+[^1]: The Tailscale client assumes HTTPS on port 443 in certain situations. Serving headscale either via HTTP or via
-    The Tailscale client assumes HTTPS on port 443 in certain situations. Serving headscale either via HTTP or via HTTPS
+    HTTPS on a port other than 443 is possible but sticking with HTTPS on port 443 is strongly recommended for
-    on a port other than 443 is possible but sticking with HTTPS on port 443 is strongly recommended for production
+    production setups. See [issue 2164](https://github.com/juanfont/headscale/issues/2164) for more information.
-    setups. See [issue 2164](https://github.com/juanfont/headscale/issues/2164) for more information.

docs/setup/upgrade.md

@@ -2,8 +2,8 @@
 
 !!! tip "Required update path"
 
-    Its required to update from one stable version to the next (e.g. 0.26.0 → 0.27.1 → 0.28.0) without
+    Its required to update from one stable version to the next (e.g. 0.26.0 → 0.27.1 → 0.28.0) without skipping minor
-    skipping minor versions in between. You should always pick the latest available patch release.
+    versions in between. You should always pick the latest available patch release.
 
 Update an existing Headscale installation to a new version:
 

docs/usage/connect/windows.md

@@ -54,6 +54,6 @@ This typically means that the registry keys above was not set appropriately.
 To reset and try again, it is important to do the following:
 
 1. Shut down the Tailscale service (or the client running in the tray)
-2. Delete Tailscale Application data folder, located at `C:\Users\<USERNAME>\AppData\Local\Tailscale` and try to connect again.
+1. Delete Tailscale Application data folder, located at `C:\Users\<USERNAME>\AppData\Local\Tailscale` and try to connect again.
-3. Ensure the Windows node is deleted from headscale (to ensure fresh setup)
+1. Ensure the Windows node is deleted from headscale (to ensure fresh setup)
-4. Start Tailscale on the Windows machine and retry the login.
+1. Start Tailscale on the Windows machine and retry the login.

docs/usage/getting-started.md

@@ -5,13 +5,13 @@ This page helps you get started with headscale and provides a few usage examples
 
 !!! note "Prerequisites"
 
-    * Headscale is installed and running as system service. Read the [setup section](../setup/requirements.md) for
+    - Headscale is installed and running as system service. Read the [setup section](../setup/requirements.md) for
       installation instructions.
-    * The configuration file exists and is adjusted to suit your environment, see
+    - The configuration file exists and is adjusted to suit your environment, see
       [Configuration](../ref/configuration.md) for details.
-    * Headscale is reachable from the Internet. Verify this by visiting the health endpoint:
+    - Headscale is reachable from the Internet. Verify this by visiting the health endpoint:
       https://headscale.example.com/health
-    * The Tailscale client is installed, see [Client and operating system support](../about/clients.md) for more
+    - The Tailscale client is installed, see [Client and operating system support](../about/clients.md) for more
       information.
 
 ## Getting help
@@ -48,9 +48,9 @@ options, run:
     communicate with the headscale service you have to make sure the unix socket is accessible by the user that runs
     the commands. In general you can achieve this by any of the following methods:
 
-      * using `sudo`
+    - using `sudo`
-      * run the commands as user `headscale`
+    - run the commands as user `headscale`
-      * add your user to the `headscale` group
+    - add your user to the `headscale` group
 
     To verify you can run the following command using your preferred method:
 
@@ -128,8 +128,7 @@ your headscale server and it also prints the registration key required to approv
 ### [Pre authenticated key](../ref/registration.md#pre-authenticated-key)
 
 It is also possible to generate a preauthkey and register a node non-interactively. First, generate a preauthkey on the
-headscale instance. By default, the key is valid for one hour and can only be used once (see `headscale preauthkeys
+headscale instance. By default, the key is valid for one hour and can only be used once (see `headscale preauthkeys --help` for other options):
---help` for other options):
 
 === "Native"