docs: restructure, clarify, consolidate existing docs (#1726)

This pull request consolidates a large set of changes to Pomerium’s documentation. It refines organization, updates integrations, removes outdated content, and simplifies navigation.

- **New Integration Guides**
  - Added guides for Apple, Auth0, Azure, Cognito, GitHub, GitLab, Google, OIDC, Okta, OneLogin, Ping, and Keycloak
  - Included images, examples, and troubleshooting steps

- **Documentation Structure Overhaul**
  - Consolidated categories (e.g., "Pomerium Zero," "Pomerium Core," "Community") into a streamlined sidebar
  - Removed outdated guidelines (Code of Conduct, Contributing) and deprecated sections
  - Merged cryptography details into the Security Policy page

- **Deployment and Kubernetes Updates**
  - Introduced new “Deploy” category, consolidating references for Kubernetes, enterprise, and device identity
  - Added quick start references, cluster management guides, and new examples
  - Updated Docker image references to `latest` tag for clarity and consistency

- **Enterprise Guides and Enhanced Features**
  - Created detailed docs for Pomerium Enterprise: installation, configuration, metrics, and clusters
  - Expanded device context, request context, and advanced policy documentation
  - Improved upgrading guides for both Pomerium Core and Enterprise

- **Security & Authentication Improvements**
  - Integrated cryptography docs into a single security-focused resource
  - Removed the standalone “Hosted Authenticate Service” section in favor of a unified authentication guide
  - Clarified JWT usage, identity verification, and zero trust concepts

- **Refinements and Cleanup**
  - Fixed or removed broken links, consolidated multiple references, and standardized paths
  - Upgraded Docusaurus and other dependencies (e.g., mermaid, redocusaurus, cspell, Prettier) for better performance
  - Improved sidebars, table formatting, and visual flow in key docs
  - Updated pre-commit workflows to ensure consistent formatting and spelling checks

These updates greatly improve the clarity, consistency, and user-friendliness of the Pomerium documentation.

Author: desimone

.github/workflows/pre-commit.yml

@@ -7,9 +7,9 @@ jobs:
   pre-commit:
     runs-on: ubuntu-latest
     steps:
-      - uses: actions/checkout@c85c95e3d7251135ab7dc9ce3241c5835cc595a9
+      - uses: actions/checkout@11bd71901bbe5b1630ceea73d27597364c9af683 #v3
         with:
           fetch-depth: 0
-      - uses: pre-commit/action@646c83fcd040023954eafda54b4db0192ce70507
+      - uses: pre-commit/action@2c7b3805fd2a0fd8c1884dcaebf91fc102a13ecd #3.0.1
         with:
           extra_args: --show-diff-on-failure --from-ref ${{ github.event.pull_request.base.sha }} --to-ref ${{ github.event.pull_request.head.sha }}

.pre-commit-config.yaml

@@ -4,10 +4,10 @@ repos:
     hooks:
       - id: prettier
         additional_dependencies:
-          - 'prettier@2.7.1'
+          - 'prettier@3.4.2'
         files: ^content\/.*$
-        exclude: content/docs/k8s/reference.md
+        exclude: content/docs/deploy/k8s/reference.md
   - repo: https://github.com/streetsidesoftware/cspell-cli
-    rev: v6.2.0
+    rev: v8.17.0
     hooks:
       - id: cspell

README.md

@@ -6,8 +6,6 @@ Pomerium's documentation is built using [Docusaurus 2](https://docusaurus.io/).
 
 ## Contributing
 
-See [Contributing](https://pomerium.com/docs/community/contributing) for more information on contributing to this project.
-
 The steps below detail the installation of this site locally for development.
 
 ### Installation

content/_generate-recovery-token.md renamed to content/docs/admonitions/_generate-recovery-token.md

@@ -1,6 +1,6 @@
 In the event that you lose access to the console via delegated access (the policy defined in Pomerium), there exists a fallback procedure to regain access to the console via a generated recovery token.
 
-![Pomerium Enterprise Recovery Sign In](docs/img/recovery-token.png)
+![Pomerium Enterprise Recovery Sign In](./img/recovery-token.png)
 
 To generate a token, run the `pomerium-console generate-recovery token` command with the following flags:
 

content/docs/admonitions/_handle-self-signed-certificate-warning.mdx

@@ -1 +1 @@
-If you notice a self-signed certificate warning, see [Handle Self-Signed Certificate Warning](/docs/troubleshooting#handle-self-signed-certificate-warning) to bypass it.
+If you notice a self-signed certificate warning, see [Handle Self-Signed Certificate Warning](/docs/internals/troubleshooting) to bypass it.

content/docs/admonitions/_import-core-config-to-zero.mdx

@@ -1,3 +1,3 @@
 Pomerium Zero provides a hosted configuration UI for managing your Pomerium configurations. You can migrate to Pomerium Zero by importing your existing configuration.
 
-See [**Import Core Config to Zero**](/docs/zero/import) for more information.
+See [**Import Core Config to Zero**](/docs/deploy/cloud/import) for more information.

content/_install-mkcert.md renamed to content/docs/admonitions/_install-mkcert.md

@@ -1,3 +1,3 @@
-When you create a [TCP](/docs/capabilities/tcp) or [Websocket](/docs/reference/routes/timeouts#websocket-connections) connection, Pomerium validates the access policy at the time the connection is made.
+When you create a [TCP](/docs/capabilities/non-http) or [Websocket](/docs/reference/routes/timeouts#websocket-connections) connection, Pomerium validates the access policy at the time the connection is made.
 
 Currently, there is no mechanism in place to terminate long-running connections if a policy becomes invalid.

content/docs/admonitions/_long-lived-connections.mdx

@@ -1,3 +1,3 @@
-Pomerium will use the [**Hosted Authenticate Service**](/docs/capabilities/hosted-authenticate-service) by default in configurations that don't specify an authenticate service URL.
+Pomerium will use the [**Hosted Authenticate Service**](/docs/capabilities/authentication) by default in configurations that don't specify an authenticate service URL.
 
-See the [**Self-Hosted Authenticate Service**](/docs/capabilities/self-hosted-authenticate-service) page if you prefer to use your own authenticate service.
+See the [**Self-Hosted Authenticate Service**](/docs/capabilities/authentication) page if you prefer to use your own authenticate service.