Reformat docs with mdformat

docs/about/contributing.md

@@ -1,3 +1,3 @@
 {%
-    include-markdown "../../CONTRIBUTING.md"
+include-markdown "../../CONTRIBUTING.md"
 %}

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.
@@ -73,12 +73,12 @@ of Headscale:
 
 1. An environment with 1000 servers
 
-     - they rarely "move" (change their endpoints)
+    - they rarely "move" (change their endpoints)
-     - new nodes are added rarely
+    - 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
+    - nodes move often, e.g. switching from home to office
 
 Headscale calculates a map of all nodes that need to talk to each other,
 creating this "world map" requires a lot of CPU time. When an event that
@@ -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?
 
@@ -179,18 +179,18 @@ following steps can be used to migrate from unsupported IP prefixes back to the
 
 - Stop Headscale
 - Restore the default prefixes in the [configuration file](../ref/configuration.md):
-  ```yaml
+    ```yaml
-  prefixes:
+    prefixes:
-    v4: 100.64.0.0/10
+      v4: 100.64.0.0/10
-    v6: fd7a:115c:a1e0::/48
+      v6: fd7a:115c:a1e0::/48
-  ```
+    ```
 - Update the `nodes.ipv4` and `nodes.ipv6` columns in the database and assign each node a unique IPv4 and IPv6 address.
   The following SQL statement assigns IP addresses based on the node ID:
-  ```sql
+    ```sql
-  UPDATE nodes
+    UPDATE nodes
-  SET ipv4=concat('100.64.', id/256, '.', id%256),
+    SET ipv4=concat('100.64.', id/256, '.', id%256),
-      ipv6=concat('fd7a:115c:a1e0::', format('%x', id));
+        ipv6=concat('fd7a:115c:a1e0::', format('%x', id));
-  ```
+    ```
 - Update the [policy](../ref/acls.md) to reflect the IP address changes (if any)
 - Start Headscale
 

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.
@@ -72,17 +72,17 @@ The gRPC interface can be used to control a Headscale instance from a remote mac
 
 ### Setup remote control
 
-1.  Download the [`headscale` binary from GitHub's release page](https://github.com/juanfont/headscale/releases). Make
+1. Download the [`headscale` binary from GitHub's release page](https://github.com/juanfont/headscale/releases). Make
-    sure to use the same version as on the server.
+   sure to use the same version as on the server.
 
-1.  Put the binary somewhere in your `PATH`, e.g. `/usr/local/bin/headscale`
+1. Put the binary somewhere in your `PATH`, e.g. `/usr/local/bin/headscale`
 
-1.  Make `headscale` executable: `chmod +x /usr/local/bin/headscale`
+1. Make `headscale` executable: `chmod +x /usr/local/bin/headscale`
 
-1.  [Create an API key](#api) on the Headscale server.
+1. [Create an API key](#api) on the Headscale server.
 
-1.  Provide the connection parameters for the remote Headscale server either via a minimal YAML configuration file or
+1. Provide the connection parameters for the remote Headscale server either via a minimal YAML configuration file or
-    via environment variables:
+   via environment variables:
 
     === "Minimal YAML configuration file"
 
@@ -102,7 +102,7 @@ The gRPC interface can be used to control a Headscale instance from a remote mac
     This instructs the `headscale` binary to connect to a remote instance at `<HEADSCALE_ADDRESS>:<PORT>`, instead of
     connecting to the local instance.
 
-1.  Test the connection by listing all nodes:
+1. Test the connection by listing all nodes:
 
     ```shell
     headscale nodes list

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

@@ -63,10 +63,10 @@ maps fetched via URL or to offer your own, custom DERP servers to nodes.
     ID. You can explicitly disable a specific region by setting its region ID to `null`. The following sample
     `derp.yaml` disables the New York DERP region (which has the region ID 1):
 
-     ```yaml title="derp.yaml"
+    ```yaml title="derp.yaml"
-     regions:
+    regions:
-       1: null
+      1: null
-     ```
+    ```
 
     Use the following configuration to serve the default DERP map (excluding New York) to nodes:
 
@@ -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

@@ -25,7 +25,7 @@ hostname and port combination "http://hostname-in-magic-dns.myvpn.example.com:30
 
     Currently, [only A and AAAA records are processed by Tailscale](https://github.com/tailscale/tailscale/blob/v1.86.5/ipn/ipnlocal/node_backend.go#L662).
 
-1.  Configure extra DNS records using one of the available configuration options:
+1. Configure extra DNS records using one of the available configuration options:
 
     === "Static entries, via `dns.extra_records`"
 
@@ -66,12 +66,12 @@ 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:
+1. Verify that DNS records are properly set using the DNS querying tool of your choice:
 
     === "Query with dig"
 
@@ -87,7 +87,7 @@ hostname and port combination "http://hostname-in-magic-dns.myvpn.example.com:30
         100.64.0.3
         ```
 
-1.  Optional: Setup the reverse proxy
+1. Optional: Setup the reverse proxy
 
     The motivating example here was to be able to access internal monitoring services on the same host without
     specifying a port, depicted as NGINX configuration snippet:

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,16 +303,16 @@ 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`.
+   OAuth is: `https://accounts.google.com`.
 
 ### Kanidm
 
@@ -323,10 +323,10 @@ Console.
   username which might be confusing as the username and email fields now contain values that look like an email address.
   [Kanidm can be configured to send the short username as `preferred_username` attribute
   instead](https://kanidm.github.io/kanidm/stable/integrations/oauth2.html#short-names):
-  ```console
+    ```console
-  kanidm system oauth2 prefer-short-username <client name>
+    kanidm system oauth2 prefer-short-username <client name>
-  ```
+    ```
-  Once configured, the short username in Headscale will be `alice` and can be referred to as `alice@` in the policy.
+    Once configured, the short username in Headscale will be `alice` and can be referred to as `alice@` in the policy.
 
 ### Keycloak
 

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/install/container.md

@@ -18,17 +18,17 @@ Registry](https://github.com/juanfont/headscale/pkgs/container/headscale). The c
 
 ## Configure and run headscale
 
-1.  Create a directory on the container host to store headscale's [configuration](../../ref/configuration.md) and the [SQLite](https://www.sqlite.org/) database:
+1. Create a directory on the container host to store headscale's [configuration](../../ref/configuration.md) and the [SQLite](https://www.sqlite.org/) database:
 
     ```shell
     mkdir -p ./headscale/{config,lib}
     cd ./headscale
     ```
 
-1.  Download the example configuration for your chosen version and save it as: `$(pwd)/config/config.yaml`. Adjust the
+1. Download the example configuration for your chosen version and save it as: `$(pwd)/config/config.yaml`. Adjust the
-    configuration to suit your local environment. See [Configuration](../../ref/configuration.md) for details.
+   configuration to suit your local environment. See [Configuration](../../ref/configuration.md) for details.
 
-1.  Start headscale from within the previously created `./headscale` directory:
+1. Start headscale from within the previously created `./headscale` directory:
 
     ```shell
     docker run \
@@ -74,7 +74,7 @@ Registry](https://github.com/juanfont/headscale/pkgs/container/headscale). The c
             test: ["CMD", "headscale", "health"]
     ```
 
-1.  Verify headscale is running:
+1. Verify headscale is running:
 
     Follow the container logs:
 

docs/setup/install/official.md

@@ -9,7 +9,7 @@ It is recommended to use our DEB packages to install headscale on a Debian based
 local user to run headscale, provide a default configuration and ship with a systemd service file. Supported
 distributions are Ubuntu 22.04 or newer, Debian 12 or newer.
 
-1.  Download the [latest headscale package](https://github.com/juanfont/headscale/releases/latest) for your platform (`.deb` for Ubuntu and Debian).
+1. Download the [latest headscale package](https://github.com/juanfont/headscale/releases/latest) for your platform (`.deb` for Ubuntu and Debian).
 
     ```shell
     HEADSCALE_VERSION="" # See above URL for latest version, e.g. "X.Y.Z" (NOTE: do not add the "v" prefix!)
@@ -18,25 +18,25 @@ distributions are Ubuntu 22.04 or newer, Debian 12 or newer.
      "https://github.com/juanfont/headscale/releases/download/v${HEADSCALE_VERSION}/headscale_${HEADSCALE_VERSION}_linux_${HEADSCALE_ARCH}.deb"
     ```
 
-1.  Install headscale:
+1. Install headscale:
 
     ```shell
     sudo apt install ./headscale.deb
     ```
 
-1.  [Configure headscale by editing the configuration file](../../ref/configuration.md):
+1. [Configure headscale by editing the configuration file](../../ref/configuration.md):
 
     ```shell
     sudo nano /etc/headscale/config.yaml
     ```
 
-1.  Enable and start the headscale service:
+1. Enable and start the headscale service:
 
     ```shell
     sudo systemctl enable --now headscale
     ```
 
-1.  Verify that headscale is running as intended:
+1. Verify that headscale is running as intended:
 
     ```shell
     sudo systemctl status headscale
@@ -56,20 +56,20 @@ This section describes the installation of headscale according to the [Requireme
 assumptions](../requirements.md#assumptions). Headscale is run by a dedicated local user and the service itself is
 managed by systemd.
 
-1.  Download the latest [`headscale` binary from GitHub's release page](https://github.com/juanfont/headscale/releases):
+1. Download the latest [`headscale` binary from GitHub's release page](https://github.com/juanfont/headscale/releases):
 
     ```shell
     sudo wget --output-document=/usr/bin/headscale \
     https://github.com/juanfont/headscale/releases/download/v<HEADSCALE VERSION>/headscale_<HEADSCALE VERSION>_linux_<ARCH>
     ```
 
-1.  Make `headscale` executable:
+1. Make `headscale` executable:
 
     ```shell
     sudo chmod +x /usr/bin/headscale
     ```
 
-1.  Add a dedicated local user to run headscale:
+1. Add a dedicated local user to run headscale:
 
     ```shell
     sudo useradd \
@@ -81,38 +81,38 @@ managed by systemd.
      headscale
     ```
 
-1.  Download the example configuration for your chosen version and save it as: `/etc/headscale/config.yaml`. Adjust the
+1. Download the example configuration for your chosen version and save it as: `/etc/headscale/config.yaml`. Adjust the
-    configuration to suit your local environment. See [Configuration](../../ref/configuration.md) for details.
+   configuration to suit your local environment. See [Configuration](../../ref/configuration.md) for details.
 
     ```shell
     sudo mkdir -p /etc/headscale
     sudo nano /etc/headscale/config.yaml
     ```
 
-1.  Copy [headscale's systemd service file](https://github.com/juanfont/headscale/blob/main/packaging/systemd/headscale.service)
+1. Copy [headscale's systemd service file](https://github.com/juanfont/headscale/blob/main/packaging/systemd/headscale.service)
-    to `/etc/systemd/system/headscale.service` and adjust it to suit your local setup. The following parameters likely need
+   to `/etc/systemd/system/headscale.service` and adjust it to suit your local setup. The following parameters likely need
-    to be modified: `ExecStart`, `WorkingDirectory`, `ReadWritePaths`.
+   to be modified: `ExecStart`, `WorkingDirectory`, `ReadWritePaths`.
 
-1.  In `/etc/headscale/config.yaml`, override the default `headscale` unix socket with a path that is writable by the
+1. In `/etc/headscale/config.yaml`, override the default `headscale` unix socket with a path that is writable by the
-    `headscale` user or group:
+   `headscale` user or group:
 
     ```yaml title="config.yaml"
     unix_socket: /var/run/headscale/headscale.sock
     ```
 
-1.  Reload systemd to load the new configuration file:
+1. Reload systemd to load the new configuration file:
 
     ```shell
     systemctl daemon-reload
     ```
 
-1.  Enable and start the new headscale service:
+1. Enable and start the new headscale service:
 
     ```shell
     systemctl enable --now headscale
     ```
 
-1.  Verify that headscale is running as intended:
+1. Verify that headscale is running as intended:
 
     ```shell
     systemctl status headscale

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"