Kiterepo · pull · Apr 23, 2026 · Apr 23, 2026 · Apr 23, 2026 · Apr 23, 2026
diff --git a/README.md b/README.md
@@ -118,7 +118,7 @@ Usage
 
 To see available commands and flags, run `ghostunnel --help`. You can get more
 information about a command by adding `--help` to the command, like `ghostunnel
-server --help` or `ghostunnel client --help`. There's also a [man page](docs/MANPAGE-linux.md).
+server --help` or `ghostunnel client --help`. There's also a [man page](docs/reference/manpage-linux.md).
 
 By default, Ghostunnel runs in the foreground and logs to stdout. You can set
 `--syslog` to log to syslog instead of stdout. If you want to run Ghostunnel
@@ -149,7 +149,7 @@ To set allowed clients, you must specify at least one of `--allow-all`,
 `--allow-cn`, `--allow-ou`, `--allow-dns`, `--allow-uri` or `--allow-policy`. All
 checks are made against the certificate of the client. Multiple flags are
 treated as a logical disjunction (OR), meaning clients can connect as long as
-any of the flags matches. See [ACCESS-FLAGS](docs/ACCESS-FLAGS.md) for more
+any of the flags matches. See [ACCESS-FLAGS](docs/security/access-flags.md) for more
 information. In this example, we assume that the CN of the client cert we want
 to accept connections from is `client`.
 
@@ -188,7 +188,7 @@ This is an example for how to launch Ghostunnel in client mode, listening on
 
 By default, Ghostunnel in client mode verifies targets based on the hostname.
 Various access control flags exist to perform additional verification on top of
-the regular hostname verification. See [ACCESS-FLAGS](docs/ACCESS-FLAGS.md) for
+the regular hostname verification. See [ACCESS-FLAGS](docs/security/access-flags.md) for
 more information.
 
 Start a backend TLS server:
@@ -275,7 +275,7 @@ also supports implementing authorization checks via [Open Policy Agent](https://
 (OPA) policies for maximum flexibility. Policies can be reloaded at runtime
 much like certificates.
 
-See [ACCESS-FLAGS](docs/ACCESS-FLAGS.md) for details.
+See [ACCESS-FLAGS](docs/security/access-flags.md) for details.
 
 [spiffe]: https://spiffe.io/
 [svid]: https://github.com/spiffe/spiffe/blob/main/standards/X509-SVID.md
@@ -323,7 +323,7 @@ obtaining and renewing a public certificate, assuming it's exposed publicly
 on tcp/443 and there are valid public DNS FQDN records that resolve to the
 listening interface IP.
 
-See [ACME](docs/ACME.md) for details.
+See [ACME](docs/certificates/acme.md) for details.
 
 ### Metrics & Profiling
 
@@ -332,15 +332,15 @@ be used to expose status and metrics information over HTTPS. The status port
 feature can be controlled via the `--status` flag. Profiling endpoints on the
 status port can be enabled with `--enable-pprof`.
 
-See [METRICS](docs/METRICS.md) for details.
+See [METRICS](docs/networking/metrics.md) for details.
 
 ### HSM/PKCS#11 support
 
 Ghostunnel has support for loading private keys from PKCS#11 modules, which
 should work with any hardware security module that exposes a PKCS#11 interface,
 including YubiKeys (via the YKCS11 module).
 
-See [HSM-PKCS11](docs/HSM-PKCS11.md) for details, including a step-by-step
+See [HSM-PKCS11](docs/certificates/hsm-pkcs11.md) for details, including a step-by-step
 guide for using Ghostunnel with a YubiKey.
 
 ### Windows/macOS Keychain Support
@@ -350,14 +350,14 @@ This is useful if you have identities stored in your local keychain that you
 want to use with Ghostunnel, e.g. if you want your private key(s) to be backed
 by the Secure Enclave on newer Touch ID MacBooks.
 
-See [KEYCHAIN](docs/KEYCHAIN.md) for details.
+See [KEYCHAIN](docs/certificates/keychain.md) for details.
 
 ### SPIFFE Workload API
 
 Ghostunnel has support for maintaining up-to-date, frequently rotated
 identities and trusted CA certificates from the SPIFFE Workload API.
 
-See [SPIFFE-WORKLOAD-API](docs/SPIFFE-WORKLOAD-API.md) for details.
+See [SPIFFE-WORKLOAD-API](docs/certificates/spiffe-workload-api.md) for details.
 
 ### Socket Activation
 
@@ -367,7 +367,7 @@ flags, and can be used by passing an address of the form `systemd:<name>` or
 `launchd:<name>`, where `<name>` should be the name of the socket as defined in
 your systemd/launchd configuration.
 
-See [SOCKET-ACTIVATION](docs/SOCKET-ACTIVATION.md) for examples.
+See [SOCKET-ACTIVATION](docs/networking/socket-activation.md) for examples.
 
 ### PROXY Protocol Support
 
@@ -378,7 +378,7 @@ to also include TLS metadata and/or client certificate details. Note that the
 backend must support the PROXY protocol and must be configured to use it when
 setting this option.
 
-See [PROXY-PROTOCOL](docs/PROXY-PROTOCOL.md) for details on modes and TLV extensions.
+See [PROXY-PROTOCOL](docs/networking/proxy-protocol.md) for details on modes and TLV extensions.
 
 ### Landlock Support
 

diff --git a/docs/SECURITY.md b/docs/SECURITY.md
diff --git a/docs/_index.md b/docs/_index.md
@@ -3,6 +3,3 @@ title: Documentation
 description: Ghostunnel documentation
 weight: 10
 ---
-
-Documentation for Ghostunnel, covering access control, certificate management,
-metrics, and platform-specific features.
diff --git a/docs/certificates/_index.md b/docs/certificates/_index.md
@@ -0,0 +1,8 @@
+---
+title: Certificates & Identity
+description: How Ghostunnel obtains, loads, and rotates certificates.
+weight: 20
+---
+
+Ghostunnel supports a variety of certificate sources, from plain PEM files on
+disk to hardware-backed keys and automatic certificate management protocols.
diff --git a/docs/ACME.md → docs/certificates/acme.md b/docs/ACME.md → docs/certificates/acme.md
@@ -1,7 +1,9 @@
 ---
 title: ACME Support
 description: Automatically obtain and renew public TLS certificates via Let's Encrypt or other ACME certificate authorities.
-weight: 30
+weight: 20
+aliases:
+  - /docs/acme/
 ---
 
 In server mode, Ghostunnel can automatically obtain and renew a public TLS

diff --git a/docs/CERTIFICATES.md → docs/certificates/formats.md b/docs/CERTIFICATES.md → docs/certificates/formats.md
@@ -1,7 +1,7 @@
 ---
 title: Certificate Formats
 description: Supported certificate and key formats, how to prepare them, and how Ghostunnel selects the right loader.
-weight: 12
+weight: 10
 ---
 
 Ghostunnel supports several certificate and private key formats. The format
@@ -76,7 +76,7 @@ cat server-cert.pem intermediate.pem server-key.pem > server-combined.pem
 PKCS#12 (`.p12` / `.pfx`) bundles the certificate chain and private key into a
 single password-protected binary file. This is also the format used when
 importing into the macOS Keychain or Windows Certificate Store (see
-[Keychain Support]({{< ref "KEYCHAIN.md" >}})).
+[Keychain Support]({{< ref "keychain.md" >}})).
 
 ```bash
 ghostunnel server \

diff --git a/docs/HSM-PKCS11.md → docs/certificates/hsm-pkcs11.md b/docs/HSM-PKCS11.md → docs/certificates/hsm-pkcs11.md
@@ -2,6 +2,8 @@
 title: HSM/PKCS#11 Support
 description: Load private keys from hardware security modules via the PKCS#11 interface.
 weight: 40
+aliases:
+  - /docs/hsm-pkcs11/
 ---
 
 Ghostunnel has support for loading private keys from [PKCS#11][pkcs11-spec]
@@ -52,7 +54,7 @@ to use environment variables to set PKCS#11 options instead of flags (via
 Note that `--cert` needs to point to the certificate chain that corresponds
 to the private key in the PKCS#11 module, with the leaf certificate being the
 first certificate in the chain (see
-[Certificate Formats]({{< ref "CERTIFICATES.md" >}})). Ghostunnel currently
+[Certificate Formats]({{< ref "formats.md" >}})). Ghostunnel currently
 cannot read the certificate chain directly from the module.
 
 ## Using a YubiKey

diff --git a/docs/KEYCHAIN.md → docs/certificates/keychain.md b/docs/KEYCHAIN.md → docs/certificates/keychain.md
@@ -2,6 +2,8 @@
 title: Keychain Support
 description: Load certificates and private keys from the macOS Keychain or Windows Certificate Store, including hardware-backed keys.
 weight: 50
+aliases:
+  - /docs/keychain/
 ---
 
 Ghostunnel can load certificates and private keys directly from the macOS

diff --git a/docs/SPIFFE-WORKLOAD-API.md → docs/certificates/spiffe-workload-api.md b/docs/SPIFFE-WORKLOAD-API.md → docs/certificates/spiffe-workload-api.md
@@ -1,7 +1,9 @@
 ---
 title: SPIFFE Workload API
 description: Automatically manage certificates and trusted roots via SPIRE or other SPIFFE-compatible workload identity providers.
-weight: 60
+weight: 30
+aliases:
+  - /docs/spiffe-workload-api/
 ---
 
 Ghostunnel can obtain certificates and trusted roots from the

diff --git a/docs/deployment/_index.md b/docs/deployment/_index.md
@@ -0,0 +1,8 @@
+---
+title: Deployment & Operations
+description: Running Ghostunnel as a container or as a supervised system service.
+weight: 50
+---
+
+Published container images and integration with systemd for running Ghostunnel
+as a long-lived service.
diff --git a/docs/DOCKER.md → docs/deployment/docker.md b/docs/DOCKER.md → docs/deployment/docker.md
@@ -1,7 +1,9 @@
 ---
 title: Docker Images
 description: Available Docker image variants and tags for running Ghostunnel in containers.
-weight: 85
+weight: 10
+aliases:
+  - /docs/docker/
 ---
 
 Docker images are published to [Docker Hub][hub] on each release. Three

diff --git a/docs/WATCHDOG.md → docs/deployment/watchdog.md b/docs/WATCHDOG.md → docs/deployment/watchdog.md
@@ -1,7 +1,9 @@
 ---
 title: Systemd Watchdog
 description: Integrate with the systemd watchdog timer for automatic restart on failure.
-weight: 85
+weight: 20
+aliases:
+  - /docs/watchdog/
 ---
 
 *Available since v1.8.0.*
@@ -59,7 +61,7 @@ WantedBy=default.target
   platforms, use `Type=simple` and manage restarts via your service manager's
   native mechanisms.
 * For socket activation with systemd, see
-  [Socket Activation]({{< ref "SOCKET-ACTIVATION.md" >}}).
+  [Socket Activation]({{< ref "socket-activation.md" >}}).
 
 [sd-notify]: https://www.freedesktop.org/software/systemd/man/latest/sd_notify.html
 [systemd-service]: https://www.freedesktop.org/software/systemd/man/latest/systemd.service.html
diff --git a/docs/getting-started/_index.md b/docs/getting-started/_index.md
@@ -0,0 +1,7 @@
+---
+title: Getting Started
+description: Quick start guide and flag overview.
+weight: 10
+---
+
+Quick start guide and flag overview.