stacklok · danbarr · Aug 27, 2025 · Aug 26, 2025 · Aug 26, 2025
diff --git a/.github/copilot-instructions.md b/.github/copilot-instructions.md
@@ -172,7 +172,8 @@ conventions for Markdown files:
 - Use the `admonition` component for notes, tips, warnings, and other
   annotations. This provides a consistent look and feel across the site.
   - Use the `:::type` syntax to define the admonition type, such as `note`,
-    `tip`, `info`, `warning`, or `danger`.
+    `tip`, `info`, `warning`, or `danger`. Use square brackets to add a title,
+    e.g. `:::info[Title]`. Add empty lines around the start and end directives.
 - Place images in `static/img` using WebP, PNG, or SVG format.
 - Use the `ThemedImage` component to provide both light and dark mode
   screenshots for apps/UIs that support both.

diff --git a/CLAUDE.md b/CLAUDE.md
@@ -172,7 +172,8 @@ conventions for Markdown files:
 - Use the `admonition` component for notes, tips, warnings, and other
   annotations. This provides a consistent look and feel across the site.
   - Use the `:::type` syntax to define the admonition type, such as `note`,
-    `tip`, `info`, `warning`, or `danger`.
+    `tip`, `info`, `warning`, or `danger`. Use square brackets to add a title,
+    e.g. `:::info[Title]`. Add empty lines around the start and end directives.
 - Place images in `static/img` using WebP, PNG, or SVG format.
 - Use the `ThemedImage` component to provide both light and dark mode
   screenshots for apps/UIs that support both.

diff --git a/docs/theme-preview.mdx b/docs/theme-preview.mdx
@@ -89,6 +89,13 @@ repository:
 These are MDX callouts
 ([reference](https://docusaurus.io/docs/markdown-features/admonitions)).
 
+To customize the title, use square brackets after the type, e.g.
+`:::tip[My title]`.
+
+To keep Prettier from invalidating the admonition syntax, add empty lines around
+the start and end of the admonition block (see
+[here](https://docusaurus.io/docs/markdown-features/admonitions#usage-with-prettier)).
+
 They can be customized in src/css/custom.css like so
 ([reference](https://docusaurus.community/knowledge/design/admonitions/#updating-the-css)):
 
@@ -119,9 +126,10 @@ This is a `tip` admonition. Its CSS class is `alert--success`.
 
 :::
 
-:::info
+:::info[Hello]
 
-This is an `info` admonition. Its CSS class is `alert--info`.
+This is an `info` admonition. Its CSS class is `alert--info` and it has a custom
+title.
 
 :::
 
@@ -137,16 +145,16 @@ This is a `danger` admonition. Its CSS class is `alert--danger`.
 
 :::
 
-:::::info Parent
+:::::info[Parent]
 
 Admonitions can be nested; example here so we can see how the colors look
 together.
 
-::::danger Child
+::::danger[Child]
 
 Child content
 
-:::tip Inception
+:::tip[Inception]
 
 This is getting silly
 

diff --git a/docs/toolhive/guides-cli/build-containers.mdx b/docs/toolhive/guides-cli/build-containers.mdx
@@ -46,7 +46,7 @@ thv build npx://@modelcontextprotocol/server-filesystem
 thv build go://github.com/example/my-mcp-server@latest
 ```
 
-:::info What's happening?
+:::info[What's happening?]
 
 When you run `thv build`, ToolHive:
 

diff --git a/docs/toolhive/guides-cli/custom-permissions.mdx b/docs/toolhive/guides-cli/custom-permissions.mdx
@@ -97,7 +97,7 @@ without creating a custom file:
   profile applied to MCP servers when you run a custom server without the
   `--permission-profile` flag.
 
-  :::important
+  :::info[Important]
 
   This profile is useful for development and testing but isn't recommended for
   production use since it doesn't restrict network destinations. Create a custom

diff --git a/docs/toolhive/guides-cli/group-management.md b/docs/toolhive/guides-cli/group-management.md
@@ -17,7 +17,7 @@ Groups let you organize MCP servers and control client access:
 - **Environment management**: Organize servers by development stage
 - **Client customization**: Configure different tool sets for different clients
 
-:::info What's the default behavior?
+:::info[What's the default behavior?]
 
 All MCP servers are automatically assigned to the `default` group unless you
 specify otherwise. MCP clients configured without a specific group can access
@@ -49,7 +49,7 @@ thv run --group development fetch
 thv run --group production filesystem --volume /prod/repo:/projects:ro
 ```
 
-:::info What's happening?
+:::info[What's happening?]
 
 When you specify a group:
 

diff --git a/docs/toolhive/guides-cli/index.mdx b/docs/toolhive/guides-cli/index.mdx
@@ -17,7 +17,7 @@ custom permissions, network access filtering, and telemetry.
 It's designed for developers who prefer working in a terminal or need to
 integrate MCP server management into scripts or automation workflows.
 
-:::tip Did you know?
+:::tip[Did you know?]
 
 The ToolHive CLI can be used alongside the
 [ToolHive UI](../guides-ui/index.mdx), which provides a graphical interface. You

diff --git a/docs/toolhive/guides-cli/network-isolation.mdx b/docs/toolhive/guides-cli/network-isolation.mdx
@@ -139,7 +139,7 @@ architecture-beta
 </TabItem>
 </Tabs>
 
-:::important
+:::info[Important]
 
 Network isolation supports HTTP and HTTPS protocols. If your MCP server needs to
 use other protocols (like direct TCP connections for database access), run it

diff --git a/docs/toolhive/guides-cli/run-mcp-servers.mdx b/docs/toolhive/guides-cli/run-mcp-servers.mdx
@@ -27,7 +27,7 @@ fetches website contents:
 thv run fetch
 ```
 
-:::info What's happening?
+:::info[What's happening?]
 
 When you run an MCP server from the registry, ToolHive:
 
@@ -249,7 +249,7 @@ thv run --name my-mcp-server --transport streamable-http my-mcp-server-image:lat
 
 Check your MCP server's documentation for the required arguments.
 
-:::info What's happening?
+:::info[What's happening?]
 
 When you run an MCP server from a Docker image, ToolHive:
 
@@ -289,7 +289,7 @@ You'll likely need to specify additional arguments like the transport method,
 volumes, and environment variables. Check your MCP server's documentation and
 see [`thv run --help`](../reference/cli/thv_run.md) for more options.
 
-:::info What's happening?
+:::info[What's happening?]
 
 When you use a protocol scheme, ToolHive:
 

diff --git a/docs/toolhive/guides-cli/secrets-management.mdx b/docs/toolhive/guides-cli/secrets-management.mdx
@@ -121,7 +121,7 @@ Alternatively, you can set a secret using standard input:
 echo "MY_SECRET_VALUE" | thv secret set <SECRET_NAME>
 ```
 
-:::tip Example
+:::tip[Example]
 
 Create a secret named `github` and set its value to your GitHub authentication
 token using the GitHub CLI:

diff --git a/docs/toolhive/guides-cli/telemetry-and-metrics.md b/docs/toolhive/guides-cli/telemetry-and-metrics.md
@@ -54,7 +54,7 @@ By default, the service name is set to `toolhive-mcp-proxy`, and the sampling
 rate is `0.1` (10%). You can customize these settings with additional
 [configuration options](#configuration-options).
 
-:::tip Recommendation
+:::tip[Recommendation]
 
 Set the `--otel-service-name` flag to a meaningful name for each MCP server.
 This helps you identify the server in your observability backend.

diff --git a/docs/toolhive/guides-k8s/intro.md b/docs/toolhive/guides-k8s/intro.md
@@ -8,7 +8,7 @@ The ToolHive Kubernetes operator manages MCP servers in Kubernetes clusters. It
 lets you define MCP servers as Kubernetes resources and automates their
 deployment and management.
 
-:::info Experimental
+:::info[Experimental]
 
 The Kubernetes operator is still under active development and isn't recommended
 for production use cases yet. Specifically, the `MCPServer` Custom Resource

diff --git a/docs/toolhive/guides-k8s/run-mcp-k8s.md b/docs/toolhive/guides-k8s/run-mcp-k8s.md
@@ -137,7 +137,7 @@ Apply the resource:
 kubectl apply -f my-mcpserver.yaml
 ```
 
-:::info What's happening?
+:::info[What's happening?]
 
 When you apply an `MCPServer` resource, here's what happens:
 
@@ -243,7 +243,7 @@ spec:
       memory: '64Mi'
 ```
 
-:::info Container name requirement
+:::info[Container name requirement]
 
 When customizing containers in `podTemplateSpec`, you must use `name: mcp` for
 the main container. This ensures the proxy can properly manage the MCP server
@@ -367,7 +367,7 @@ to learn how to connect to MCP servers using different clients.
 - [Custom permissions](../guides-cli/custom-permissions.mdx) - Configure
   permission profiles
 
-:::important
+:::info[Important]
 
 Outbound network filtering using permission profiles isn't currently implemented
 in the ToolHive Operator. This is a roadmap feature planned for future releases.

diff --git a/docs/toolhive/guides-ui/index.mdx b/docs/toolhive/guides-ui/index.mdx
@@ -34,7 +34,7 @@ simple way to get started.
 We strive to make ToolHive intuitive and easy to use. If we've missed the mark
 on something, [let us know](https://discord.gg/stacklok)!
 
-:::tip Advanced users
+:::tip[Advanced users]
 
 If you want more control or want to experiment with more advanced features like
 custom permissions and telemetry, the ToolHive UI can work side-by-side with the

diff --git a/docs/toolhive/guides-ui/install.mdx b/docs/toolhive/guides-ui/install.mdx
@@ -53,7 +53,7 @@ and run the setup executable.
 
 After installation, you can find ToolHive in your Start menu or on your desktop.
 
-:::important
+:::info[Important]
 
 The first time you run ToolHive, you may be prompted to allow firewall access.
 If you don't allow this, ToolHive won't be able to run MCP servers.

diff --git a/docs/toolhive/guides-ui/network-isolation.mdx b/docs/toolhive/guides-ui/network-isolation.mdx
@@ -54,7 +54,7 @@ access:
   services or resources. For example, port 443 is the default port for HTTPS
   connections.
 
-:::important
+:::info[Important]
 
 If you do not specify any allowed hosts or ports, the MCP server will not be
 able to access any external resources, including the internet. This can be

diff --git a/docs/toolhive/guides-ui/secrets-management.md b/docs/toolhive/guides-ui/secrets-management.md
@@ -48,7 +48,7 @@ Your ToolHive secrets are managed on the **Secrets** page. Here you can:
   - Update the secret value
   - Delete the secret
 
-:::important
+:::warning
 
 If you delete a secret that is in use by an MCP server, the server will continue
 running but you will not be able to restart it if stopped. You'll need to remove

diff --git a/docs/toolhive/tutorials/quickstart-cli.mdx b/docs/toolhive/tutorials/quickstart-cli.mdx
@@ -105,7 +105,7 @@ thv client setup
 Select one or more clients from the list using the spacebar to toggle selection.
 Press Enter to confirm your selection.
 
-:::info What's happening?
+:::info[What's happening?]
 
 When you run the setup command, ToolHive automatically finds
 [supported clients](../reference/client-compatibility.mdx) on your system. When
@@ -152,7 +152,7 @@ notion     Official Notion MCP server.                                    Offici
 
 This shows all the MCP servers available in the ToolHive registry.
 
-:::info What's happening?
+:::info[What's happening?]
 
 ToolHive maintains a curated registry of MCP servers that have been verified to
 work correctly. The registry includes information about what each server does
@@ -196,7 +196,7 @@ Status: Image is up to date for ghcr.io/stackloklabs/gofetch/server:latest
 8:41AM INF Use 'thv stop fetch' to stop the server
 ```
 
-:::info What's happening?
+:::info[What's happening?]
 
 When you run an MCP server, ToolHive:
 
@@ -227,7 +227,7 @@ fetch   ghcr.io/stackloklabs/gofetch/server:latest   running   http://127.0.0.1:
 
 This confirms that the fetch server is running and available on port 49226.
 
-:::info What's happening?
+:::info[What's happening?]
 
 ToolHive keeps track of all the MCP servers it's managing. The
 [`list`](../reference/cli/thv_list.md) command shows you which servers are
@@ -248,7 +248,7 @@ and summarize it for me?"
 The AI should be able to use the Fetch MCP server to retrieve the content and
 provide a summary.
 
-:::info What's happening?
+:::info[What's happening?]
 
 When you ask the AI to fetch content, it detects that it needs external data. It
 discovers the fetch tool provided by your MCP server, calls the tool with the
@@ -271,7 +271,7 @@ If you want to remove it completely:
 thv rm fetch
 ```
 
-:::info What's happening?
+:::info[What's happening?]
 
 Stopping a server pauses it and terminates the associated proxy process but
 keeps the container around so you can restart it quickly later using

diff --git a/docs/toolhive/tutorials/quickstart-k8s.mdx b/docs/toolhive/tutorials/quickstart-k8s.mdx
@@ -89,7 +89,7 @@ CoreDNS is running at https://127.0.0.1:xxxxx/api/v1/namespaces/kube-system/serv
 
 This confirms your cluster is running and ready for the ToolHive operator.
 
-:::info What's happening?
+:::info[What's happening?]
 
 Kind (Kubernetes in Docker) creates a local Kubernetes cluster using Docker
 containers. This is perfect for development and testing because it's isolated
@@ -129,7 +129,7 @@ toolhive-operator-xxx   1/1     Running   0          30s
 
 If the pod shows "Running" status, your operator is ready to manage MCP servers.
 
-:::info What's happening?
+:::info[What's happening?]
 
 The ToolHive operator is a Kubernetes controller that watches for `MCPServer`
 resources. When you create an `MCPServer` resource, the operator automatically
@@ -149,7 +149,7 @@ Apply the example `fetch` MCP server from the ToolHive repository:
 kubectl apply -f https://raw.githubusercontent.com/stacklok/toolhive/refs/heads/main/examples/operator/mcp-servers/mcpserver_fetch.yaml
 ```
 
-:::info What's happening?
+:::info[What's happening?]
 
 When you create an `MCPServer` resource, the ToolHive operator detects it and
 automatically:
@@ -201,7 +201,7 @@ You should see a response of `OK`.
 
 This confirms your MCP server is running and responding correctly.
 
-:::info What's happening?
+:::info[What's happening?]
 
 The ToolHive operator automatically creates a Kubernetes service for each MCP
 server. This service provides a stable network endpoint that other applications
@@ -314,7 +314,7 @@ retrieve the content and provide a summary.
   className='screenshot'
 />
 
-:::info What's happening?
+:::info[What's happening?]
 
 You're manually configuring VS Code to connect to your MCP server running in
 Kubernetes. The port-forward creates a tunnel from your local machine
@@ -396,7 +396,7 @@ You should see:
 No resources found in toolhive-system namespace.
 ```
 
-:::info What's happening?
+:::info[What's happening?]
 
 When you delete an `MCPServer` resource, the operator automatically cleans up
 all the associated Kubernetes resources (pods, services, etc.). This ensures no
@@ -410,7 +410,7 @@ When you're completely finished, delete the kind cluster:
 kind delete cluster --name toolhive
 ```
 
-:::tip For Task users
+:::tip[For Task users]
 
 If you followed the [TL;DR setup](#quickstart-with-task-tldr) using Task, you
 can also run:

diff --git a/docs/toolhive/tutorials/quickstart-ui.mdx b/docs/toolhive/tutorials/quickstart-ui.mdx
@@ -51,7 +51,7 @@ On the initial splash screen, click **Browse registry**, or open the
 **Registry** page from the top menu bar. This page lists the MCP servers in
 ToolHive's built-in registry.
 
-:::info What is this?
+:::info[What is this?]
 
 ToolHive maintains a curated registry of MCP servers that have been verified to
 work correctly. The registry includes information about what each server does
@@ -71,7 +71,7 @@ start the installation.
 
 Once the server is installed, it will appear on the **MCP Servers** page.
 
-:::info What's happening?
+:::info[What's happening?]
 
 ToolHive downloads the container image for the fetch server, creates a container
 with the appropriate security settings, and starts the server. It also sets up a
@@ -87,7 +87,7 @@ servers you have installed.
 
 Click the toggle switch to connect the client you want to use.
 
-:::info What's happening?
+:::info[What's happening?]
 
 When you connect a supported client, ToolHive automatically configures it to use
 MCP servers that you install. This means you don't have to manually configure
@@ -108,7 +108,7 @@ and summarize it for me?"
 The AI should be able to use the Fetch MCP server to retrieve the content and
 provide a summary.
 
-:::info What's happening?
+:::info[What's happening?]
 
 When you ask the AI agent to fetch content, the large language model (LLM)
 determines that it needs external data. It discovers the fetch tool provided by