Use collapsible blocks for troubleshooting notes (#35)

* Update troubleshooting sections with collapsible blocks

* Clean up README badge links

* Fix formatting

Author: danbarr

.markdownlint.json

@@ -20,6 +20,9 @@
     "tables": false
   },
   "no-bare-urls": false,
+  "no-inline-html": {
+    "allowed_elements": ["details", "summary"]
+  },
   "proper-names": {
     "code_blocks": false,
     "names": ["Copilot", "GitHub", "ToolHive"]

README.md

@@ -1,6 +1,6 @@
 # Stacklok docs <!-- omit in toc -->
 
-[![GitHub deployments](https://img.shields.io/github/deployments/stacklok/docs-website/Production?logo=vercel&style=flat&label=Vercel%20deployment)](https://github.com/stacklok/docs-website/deployments/Production)
+[![GitHub deployments][deployment-img]][deployment]
 
 This repository contains the public-facing docs for Stacklok's projects, hosted
 at [https://docs.stacklok.com](https://docs.stacklok.com).
@@ -26,7 +26,7 @@ You'll need Node.js available (v22 recommended) or VS Code with the
 [Dev Containers](https://marketplace.visualstudio.com/items?itemName=ms-vscode-remote.remote-containers)
 extension and Docker.
 
-[![Open in Dev Containers](https://img.shields.io/static/v1?label=Dev%20Containers&message=Open&color=blue)](https://vscode.dev/redirect?url=vscode://ms-vscode-remote.remote-containers/cloneInVolume?url=https://github.com/stacklok/docs-website)
+[![Open in Dev Containers][devcontainer-img]][devcontainer]
 
 ```bash
 npm install
@@ -80,3 +80,13 @@ the `main` branch.
 ## About
 
 This site is built with [Docusaurus](https://docusaurus.io/).
+
+<!-- badge links -->
+
+[deployment-img]:
+  https://img.shields.io/github/deployments/stacklok/docs-website/Production?logo=vercel&label=Vercel%20deployment
+[deployment]: https://github.com/stacklok/docs-website/deployments/Production
+[devcontainer-img]:
+  https://img.shields.io/static/v1?label=Dev%20Containers&message=Open&color=blue
+[devcontainer]:
+  https://vscode.dev/redirect?url=vscode://ms-vscode-remote.remote-containers/cloneInVolume?url=https://github.com/stacklok/docs-website

docs/toolhive/guides-cli/client-configuration.md

@@ -160,7 +160,8 @@ ToolHive provides.
 
 ## Troubleshooting
 
-### Client is not detected by `thv client setup`
+<details>
+<summary>Client is not detected by `thv client setup`</summary>
 
 If ToolHive doesn't detect your client:
 
@@ -177,7 +178,10 @@ If ToolHive doesn't detect your client:
    thv config register-client <CLIENT_NAME>
    ```
 
-### Client can't connect to MCP server
+</details>
+
+<details>
+<summary>Client can't connect to MCP server</summary>
 
 If your client can't connect to the MCP server:
 
@@ -202,7 +206,10 @@ If your client can't connect to the MCP server:
 
 4. Restart your client application.
 
-### Client can connect but tools aren't available
+</details>
+
+<details>
+<summary>Client can connect but tools aren't available</summary>
 
 If your client connects to the MCP server but tools aren't available:
 
@@ -227,7 +234,10 @@ If your client connects to the MCP server but tools aren't available:
 5. If you've implemented authentication for your MCP server, make sure the
    client has the necessary permissions to access the tools.
 
-### Containerized client can't connect to MCP server
+</details>
+
+<details>
+<summary>Containerized client can't connect to MCP server</summary>
 
 If you're running an MCP client inside a container and it can't connect to an
 MCP server running on the same host, make sure you use the correct host address.
@@ -242,7 +252,10 @@ connectivity.
 Refer to your containerization platform's documentation for details on how to
 configure network access between containers and the host.
 
-### VS Code can't connect to some streamable-http servers
+</details>
+
+<details>
+<summary>VS Code can't connect to some streamable-http servers</summary>
 
 You might encounter errors with Visual Studio Code connecting to some
 Python-based MCP servers using the Streamable HTTP transport protocol:
@@ -267,3 +280,5 @@ There are two workarounds:
 
 You can track a proposed fix for this issue in the
 [MCP Python SDK repository](https://github.com/modelcontextprotocol/python-sdk/pull/781).
+
+</details>

docs/toolhive/guides-cli/custom-permissions.mdx

@@ -349,7 +349,8 @@ When creating and using permission profiles:
 
 ## Troubleshooting
 
-### File system access issues
+<details>
+<summary>File system access issues</summary>
 
 If your MCP server can't access the file system as expected:
 
@@ -365,7 +366,10 @@ If your MCP server can't access the file system as expected:
 
 4. Restart the server with the updated profile or a corrected volume mount
 
-### Network connectivity issues
+</details>
+
+<details>
+<summary>Network connectivity issues</summary>
 
 If your MCP server can't connect to external services:
 
@@ -381,3 +385,5 @@ If your MCP server can't connect to external services:
 
 4. Try temporarily using the default `network` profile to confirm it's a
    permissions issue
+
+</details>

docs/toolhive/guides-cli/install.mdx

@@ -323,7 +323,8 @@ MCP servers. See [Explore the registry](./registry.md) and
 
 ## Troubleshooting
 
-### Permission denied errors
+<details>
+<summary>Permission denied errors</summary>
 
 If you see "permission denied" errors when running ToolHive:
 
@@ -346,7 +347,10 @@ If you see "permission denied" errors when running ToolHive:
    [Docker documentation](https://docs.docker.com/engine/install/linux-postinstall/#manage-docker-as-a-non-root-user)
    for more details.
 
-### Upgrade error on Windows
+</details>
+
+<details>
+<summary>Upgrade error on Windows</summary>
 
 If you encounter an error when upgrading ToolHive on Windows, it may be due to
 the ToolHive executable being locked by a running MCP server proxy.
@@ -383,6 +387,8 @@ To resolve this:
    # repeat for each server
    ```
 
+</details>
+
 ### Other issues
 
 For other installation issues, check the

docs/toolhive/guides-cli/run-mcp-servers.mdx

@@ -383,7 +383,8 @@ control your servers.
 
 ## Troubleshooting
 
-### Server fails to start
+<details>
+<summary>Server fails to start</summary>
 
 If a server fails to start:
 
@@ -392,7 +393,10 @@ If a server fails to start:
 3. Check if the port is already in use
 4. Look at the error message for specific issues
 
-### Server starts but isn't accessible
+</details>
+
+<details>
+<summary>Server starts but isn't accessible</summary>
 
 If a server starts but isn't accessible:
 
@@ -407,7 +411,10 @@ If a server starts but isn't accessible:
 3. Make sure clients are properly configured (see
    [Client configuration](client-configuration.md))
 
-### Server crashes or exits unexpectedly
+</details>
+
+<details>
+<summary>Server crashes or exits unexpectedly</summary>
 
 If a server crashes or exits unexpectedly:
 
@@ -430,3 +437,5 @@ If a server crashes or exits unexpectedly:
    ```
 
 4. Check if the server requires any secrets or environment variables
+
+</details>

docs/toolhive/guides-cli/secrets-management.mdx

@@ -278,7 +278,8 @@ in the `MCPVault` vault and passes them to the `slack` MCP server as the
 
 ## Troubleshooting
 
-### Keyring access issues
+<details>
+<summary>Keyring access issues</summary>
 
 If you run into errors related to the system keyring:
 
@@ -294,7 +295,10 @@ If you run into errors related to the system keyring:
    sudo dnf install gnome-keyring
    ```
 
-### Secret not available to MCP server
+</details>
+
+<details>
+<summary>Secret not available to MCP server</summary>
 
 If your MCP server can't access a secret:
 
@@ -324,13 +328,19 @@ If your MCP server can't access a secret:
    thv logs <server-name>
    ```
 
-### Forgot encryption password
+</details>
+
+<details>
+<summary>Forgot encryption password</summary>
 
 If the keyring entry is lost or corrupted and you forget your encryption
 password, you won't be able to access your secrets. In this case, delete the
 [encrypted secrets file](#reset-your-secret-store) and recreate your secrets.
 
-### Issues accessing 1Password secrets
+</details>
+
+<details>
+<summary>Issues accessing 1Password secrets</summary>
 
 If you can't access 1Password secrets:
 
@@ -353,3 +363,5 @@ If you can't access 1Password secrets:
    ```bash
    thv secret get op://<vault-name>/<item-name>/[section-name/]<field-name>
    ```
+
+</details>

docs/toolhive/guides-k8s/deploy-operator-helm.md

@@ -246,7 +246,8 @@ configured during installation.
 
 ## Troubleshooting
 
-### Authentication error with ghcr.io
+<details>
+<summary>Authentication error with ghcr.io</summary>
 
 If you encounter an authentication error when pulling the Helm chart, it might
 indicate a problem with your access to the GitHub Container Registry
@@ -259,7 +260,10 @@ your token has expired or been revoked.
 See the GitHub documentation to
 [re-authenticate to the registry](https://docs.github.com/en/packages/working-with-a-github-packages-registry/working-with-the-container-registry#authenticating-with-a-personal-access-token-classic).
 
-### Operator pod fails to start
+</details>
+
+<details>
+<summary>Operator pod fails to start</summary>
 
 If the operator pod is not starting or is in a `CrashLoopBackOff` state, check
 the pod logs for error messages:
@@ -284,7 +288,10 @@ Common causes include:
   resources available
 - **Image pull issues**: Verify that the cluster can pull images from `ghcr.io`
 
-### CRDs installation fails
+</details>
+
+<details>
+<summary>CRDs installation fails</summary>
 
 If the CRDs installation fails, you might see errors about existing resources or
 permission issues:
@@ -304,7 +311,10 @@ helm uninstall toolhive-operator-crds
 helm upgrade -i toolhive-operator-crds oci://ghcr.io/stacklok/toolhive/toolhive-operator-crds
 ```
 
-### Namespace creation issues
+</details>
+
+<details>
+<summary>Namespace creation issues</summary>
 
 If you encounter permission errors when creating the `toolhive-system`
 namespace, create it manually first:
@@ -319,7 +329,10 @@ Then install the operator without the `--create-namespace` flag:
 helm upgrade -i toolhive-operator oci://ghcr.io/stacklok/toolhive/toolhive-operator -n toolhive-system
 ```
 
-### Helm chart not found
+</details>
+
+<details>
+<summary>Helm chart not found</summary>
 
 If Helm cannot find the chart, ensure you're using the correct OCI registry URL
 and that your Helm version supports OCI registries (v3.8.0+):
@@ -332,10 +345,15 @@ helm version
 helm pull oci://ghcr.io/stacklok/toolhive/toolhive-operator
 ```
 
-### Network connectivity issues
+</details>
+
+<details>
+<summary>Network connectivity issues</summary>
 
 If you're experiencing network timeouts or connection issues:
 
 - Verify your cluster has internet access to reach `ghcr.io`
 - Check if your organization uses a proxy or firewall that might block access
 - Consider using a private registry mirror if direct access is restricted
+
+</details>