Utilize admonitions

alukach · alukach · commit 68c374694e2e · 2026-03-02T11:58:34.000-08:00
diff --git a/docs/architecture/crate-layout.md b/docs/architecture/crate-layout.md
@@ -69,9 +69,8 @@ The Cloudflare Workers WASM runtime:
 - JS `ReadableStream` passthrough for zero-copy streaming
 - Config loading from env vars (`PROXY_CONFIG`)
 
-::: warning
-This crate is excluded from the workspace `default-members` because WASM types are `!Send` and won't compile on native targets. Always build with `--target wasm32-unknown-unknown`.
-:::
+> [!WARNING]
+> This crate is excluded from the workspace `default-members` because WASM types are `!Send` and won't compile on native targets. Always build with `--target wasm32-unknown-unknown`.
 
 ### `source-coop` (lib)
 
diff --git a/docs/architecture/request-lifecycle.md b/docs/architecture/request-lifecycle.md
@@ -72,19 +72,17 @@ Used for: **LIST, errors, synthetic responses**
 
 For LIST operations, the handler calls `object_store::list_with_delimiter()` via the backend's store, builds S3 `ListObjectsV2` XML from the results, and returns it as a complete response. If a `ListRewrite` is configured, key prefixes are transformed in the XML.
 
-::: info
-LIST returns all results in a single response. `IsTruncated` is always `false`. The proxy does not support S3-style pagination with continuation tokens.
-:::
+> [!NOTE]
+> LIST returns all results in a single response. `IsTruncated` is always `false`. The proxy does not support S3-style pagination with continuation tokens.
 
 ### `NeedsBody(PendingRequest)`
 
 Used for: **CreateMultipartUpload, UploadPart, CompleteMultipartUpload, AbortMultipartUpload**
 
 Multipart operations need the request body (e.g., the XML body for `CompleteMultipartUpload`). The runtime materializes the body, then calls `handler.handle_with_body()`, which signs the request using `S3RequestSigner` and sends it via `backend.send_raw()`.
 
-::: warning
-Multipart uploads are only supported for `backend_type = "s3"`. Non-S3 backends should use single PUT requests (object_store handles chunking internally).
-:::
+> [!WARNING]
+> Multipart uploads are only supported for `backend_type = "s3"`. Non-S3 backends should use single PUT requests (object_store handles chunking internally).
 
 ## Response Header Forwarding
 
diff --git a/docs/auth/backend-auth.md b/docs/auth/backend-auth.md
@@ -113,9 +113,8 @@ When OIDC provider keys are configured, the proxy serves two well-known endpoint
 }
 ```
 
-::: warning
-These endpoints must be publicly accessible. Cloud providers fetch them at JWT validation time to verify signatures. If they are behind a firewall or VPN, credential exchange will fail.
-:::
+> [!WARNING]
+> These endpoints must be publicly accessible. Cloud providers fetch them at JWT validation time to verify signatures. If they are behind a firewall or VPN, credential exchange will fail.
 
 ### The Exchange Flow in Detail
 
@@ -148,9 +147,8 @@ On subsequent requests, cached credentials are reused until they expire.
      --thumbprint-list <thumbprint>
    ```
 
-   ::: tip
-   To get the thumbprint, fetch the TLS certificate chain from your proxy's domain. AWS uses this to verify the HTTPS connection to the JWKS endpoint.
-   :::
+   > [!TIP]
+   > To get the thumbprint, fetch the TLS certificate chain from your proxy's domain. AWS uses this to verify the HTTPS connection to the JWKS endpoint.
 
 2. **Create an IAM Role** with a trust policy that allows the proxy to assume it:
    ```json
@@ -210,9 +208,8 @@ On subsequent requests, cached credentials are reused until they expire.
 
 ### Azure Blob Storage
 
-::: info Planned
-Azure OIDC backend auth is planned but not yet implemented. The proxy currently supports Azure with static credentials only.
-:::
+> [!NOTE]
+> **Planned** — Azure OIDC backend auth is planned but not yet implemented. The proxy currently supports Azure with static credentials only.
 
 **Planned setup:**
 
@@ -223,9 +220,8 @@ Azure OIDC backend auth is planned but not yet implemented. The proxy currently
 
 ### Google Cloud Storage
 
-::: info Planned
-GCS OIDC backend auth is planned but not yet implemented. The proxy currently supports GCS with static credentials only.
-:::
+> [!NOTE]
+> **Planned** — GCS OIDC backend auth is planned but not yet implemented. The proxy currently supports GCS with static credentials only.
 
 **Planned setup:**
 
diff --git a/docs/auth/proxy-auth.md b/docs/auth/proxy-auth.md
@@ -23,7 +23,8 @@ backend_type = "s3"
 anonymous_access = true
 ```
 
-Anonymous access only allows `GetObject`, `HeadObject`, and `ListBucket`. Write operations always require authentication.
+> [!NOTE]
+> Anonymous access only allows `GetObject`, `HeadObject`, and `ListBucket`. Write operations always require authentication.
 
 ## Long-Lived Access Keys
 
diff --git a/docs/auth/sealed-tokens.md b/docs/auth/sealed-tokens.md
@@ -47,9 +47,8 @@ export SESSION_TOKEN_KEY="<base64-encoded-32-byte-key>"
 
 This key must be the same across all instances of the proxy. If you rotate the key, all existing session tokens become invalid — clients will need to re-authenticate.
 
-::: warning
-`SESSION_TOKEN_KEY` is required for the Cloudflare Workers runtime. Without it, temporary credentials from STS cannot be verified on subsequent requests.
-:::
+> [!WARNING]
+> `SESSION_TOKEN_KEY` is required for the Cloudflare Workers runtime. Without it, temporary credentials from STS cannot be verified on subsequent requests.
 
 ## Scope Behavior
 
diff --git a/docs/configuration/buckets.md b/docs/configuration/buckets.md
@@ -55,9 +55,8 @@ secret_access_key = "..."
 
 ### Azure Blob Storage
 
-::: info
-Requires the `azure` feature flag on `source-coop-core`. Enabled by default in the server runtime, not available in CF Workers.
-:::
+> [!NOTE]
+> Requires the `azure` feature flag on `source-coop-core`. Enabled by default in the server runtime, not available in CF Workers.
 
 ```toml
 [buckets.backend_options]
@@ -75,9 +74,8 @@ access_key = "..."
 
 ### Google Cloud Storage
 
-::: info
-Requires the `gcp` feature flag on `source-coop-core`. Enabled by default in the server runtime, not available in CF Workers.
-:::
+> [!NOTE]
+> Requires the `gcp` feature flag on `source-coop-core`. Enabled by default in the server runtime, not available in CF Workers.
 
 ```toml
 [buckets.backend_options]
diff --git a/docs/configuration/credentials.md b/docs/configuration/credentials.md
@@ -48,7 +48,8 @@ Long-lived credentials are appropriate for:
 - **Development and testing** environments
 - **Environments without an OIDC provider**
 
-For CI/CD workflows and user-facing applications, prefer [OIDC/STS temporary credentials](/auth/proxy-auth#oidcsts-temporary-credentials) for better security (automatic expiration, no stored secrets).
+> [!TIP]
+> For CI/CD workflows and user-facing applications, prefer [OIDC/STS temporary credentials](/auth/proxy-auth#oidcsts-temporary-credentials) — they expire automatically and avoid storing secrets in config.
 
 ## Disabling Credentials
 
diff --git a/docs/configuration/providers/dynamodb.md b/docs/configuration/providers/dynamodb.md
@@ -28,6 +28,5 @@ The provider uses a single-table design with partition key (`PK`) and sort key (
 - Serverless deployments where a database server isn't practical
 - High-availability requirements (DynamoDB's built-in replication)
 
-::: tip
-Wrap the DynamoDB provider with [CachedProvider](./cached) to reduce read costs and latency.
-:::
+> [!TIP]
+> Wrap the DynamoDB provider with [CachedProvider](./cached) to reduce read costs and latency.
diff --git a/docs/configuration/providers/postgres.md b/docs/configuration/providers/postgres.md
@@ -23,6 +23,5 @@ let provider = PostgresProvider::new(pool);
 - Relational data management preferences
 - Complex queries or joins with other application data
 
-::: tip
-Wrap the PostgreSQL provider with [CachedProvider](./cached) to reduce query load and latency.
-:::
+> [!TIP]
+> Wrap the PostgreSQL provider with [CachedProvider](./cached) to reduce query load and latency.
diff --git a/docs/configuration/roles.md b/docs/configuration/roles.md
@@ -104,7 +104,8 @@ Prefix matching follows these rules:
 - If the prefix ends with `/` or is empty: the key must start with the prefix
 - Otherwise: the key must equal the prefix exactly, or start with the prefix followed by `/`
 
-This prevents a prefix like `data` from accidentally matching `data-private/secret.txt`. The prefix `data/` would only match keys under the `data/` directory.
+> [!IMPORTANT]
+> A prefix without a trailing `/` must match exactly or be followed by `/`. This prevents `data` from matching `data-private/secret.txt`. Use `data/` to restrict to that directory.
 
 ## Template Variables
 
diff --git a/docs/deployment/cloudflare-workers.md b/docs/deployment/cloudflare-workers.md
@@ -4,9 +4,10 @@ The CF Workers runtime deploys the proxy to Cloudflare's edge network. It compil
 
 ## Limitations
 
-- **S3 backends only** — Azure and GCS are not supported on WASM
-- **Static or API config only** — DynamoDB and Postgres providers require Tokio, which is unavailable
-- **`SESSION_TOKEN_KEY` required** — Workers are stateless, so sealed tokens are the only way to persist temporary credentials
+> [!WARNING]
+> - **S3 backends only** — Azure and GCS are not supported on WASM
+> - **Static or API config only** — DynamoDB and Postgres providers require Tokio, which is unavailable
+> - **`SESSION_TOKEN_KEY` required** — Workers are stateless, so sealed tokens are the only way to persist temporary credentials
 
 ## Configuration
 
@@ -65,9 +66,8 @@ cd crates/runtimes/cf-workers
 npx wrangler build
 ```
 
-::: warning
-Always use `--target wasm32-unknown-unknown` when checking or building the CF Workers crate. It is excluded from the workspace `default-members` because WASM types won't compile on native targets.
-:::
+> [!WARNING]
+> Always use `--target wasm32-unknown-unknown` when checking or building the CF Workers crate. It is excluded from the workspace `default-members` because WASM types won't compile on native targets.
 
 ## Development
 
diff --git a/docs/getting-started/index.md b/docs/getting-started/index.md
@@ -1,6 +1,7 @@
 # Quick Start
 
-This guide is for administrators setting up and running their own Source Data Proxy. If you're a user looking to access data through an existing proxy, see the [User Guide](/guide/).
+> [!NOTE]
+> This guide is for administrators setting up and running their own Source Data Proxy. If you're a user looking to access data through an existing proxy, see the [User Guide](/guide/).
 
 The Source Data Proxy is a multi-runtime S3 gateway that proxies requests to backend object stores. This guide gets you running locally in minutes.
 
diff --git a/docs/guide/client-usage.md b/docs/guide/client-usage.md
@@ -86,7 +86,8 @@ curl https://data.source.coop/public-data/hello.txt
 curl -I https://data.source.coop/public-data/hello.txt
 ```
 
-For authenticated requests, use aws-cli or an SDK that handles SigV4 signing.
+> [!NOTE]
+> Authenticated requests require SigV4 signing. Use aws-cli or an SDK rather than raw curl.
 
 ## Request Styles
 
diff --git a/docs/guide/endpoints.md b/docs/guide/endpoints.md
@@ -97,6 +97,5 @@ flowchart TD
 | EC2 in us-east-1, data in us-west-2 | `data.source.coop` | Cross-region: Cloudflare backbone is faster than cross-region AWS traffic |
 | SageMaker in us-west-2 | `us-west-2.data.source.coop` | Same-region: zero egress for training data |
 
-::: tip
-All endpoints support the same authentication methods and S3 operations. Your credentials work across any endpoint — only the `endpoint_url` changes.
-:::
+> [!TIP]
+> All endpoints support the same authentication methods and S3 operations. Your credentials work across any endpoint — only the `endpoint_url` changes.
diff --git a/docs/reference/errors.md b/docs/reference/errors.md
@@ -53,6 +53,5 @@ STS errors follow the AWS STS error format:
 
 ## Error Message Safety
 
-For 5xx errors, the proxy returns generic messages to avoid leaking internal infrastructure details. The full error message is logged server-side but not exposed to clients.
-
-For 4xx errors, the proxy returns descriptive messages to help clients debug authentication and authorization issues.
+> [!NOTE]
+> For 5xx errors, the proxy returns generic messages to avoid leaking internal infrastructure details. The full error is logged server-side but not exposed to clients. For 4xx errors, descriptive messages are returned to help clients debug authentication and authorization issues.
diff --git a/docs/reference/operations.md b/docs/reference/operations.md
@@ -38,6 +38,7 @@ These are served when `OIDC_PROVIDER_KEY` and `OIDC_PROVIDER_ISSUER` are configu
 
 ## Limitations
 
-- **LIST returns all results** — `object_store::list_with_delimiter()` fetches all pages internally. `IsTruncated` is always `false`. Continuation tokens and max-keys are not supported.
-- **Multipart is S3 only** — Multipart operations use raw HTTP with `S3RequestSigner` and are gated to `backend_type = "s3"`. Non-S3 backends should use single PUT requests.
-- **DeleteObject does not return confirmation** — The proxy forwards the DELETE and returns the backend's response status.
+> [!WARNING]
+> - **LIST returns all results** — `object_store::list_with_delimiter()` fetches all pages internally. `IsTruncated` is always `false`. Continuation tokens and max-keys are not supported.
+> - **Multipart is S3 only** — Multipart operations use raw HTTP with `S3RequestSigner` and are gated to `backend_type = "s3"`. Non-S3 backends should use single PUT requests.
+> - **DeleteObject does not return confirmation** — The proxy forwards the DELETE and returns the backend's response status.
