docs: touch ups to harmonize rendering on docs website

cmd/docker-mcp/commands/client.go

@@ -51,7 +51,7 @@ func connectClientCommand(cwd string, cfg client.Config) *cobra.Command {
 	}
 	cmd := &cobra.Command{
 		Use:   fmt.Sprintf("connect [OPTIONS] <mcp-client>\n\nSupported clients: %s", strings.Join(client.GetSupportedMCPClients(cfg), " ")),
-		Short: "Connect the Docker MCP Toolkit to a client",
+		Short: fmt.Sprintf("Connect the Docker MCP Toolkit to a client. Supported clients: %s", strings.Join(client.GetSupportedMCPClients(cfg), " ")),
 		Args:  cobra.ExactArgs(1),
 		RunE: func(cmd *cobra.Command, args []string) error {
 			return client.Connect(cmd.Context(), cwd, cfg, args[0], opts.Global, opts.Quiet)
@@ -70,7 +70,7 @@ func disconnectClientCommand(cwd string, cfg client.Config) *cobra.Command {
 	}
 	cmd := &cobra.Command{
 		Use:   fmt.Sprintf("disconnect [OPTIONS] <mcp-client>\n\nSupported clients: %s", strings.Join(client.GetSupportedMCPClients(cfg), " ")),
-		Short: "Disconnect the Docker MCP Toolkit from a client",
+		Short: fmt.Sprintf("Disconnect the Docker MCP Toolkit from a client. Supported clients: %s", strings.Join(client.GetSupportedMCPClients(cfg), " ")),
 		Args:  cobra.ExactArgs(1),
 		RunE: func(cmd *cobra.Command, args []string) error {
 			return client.Disconnect(cmd.Context(), cwd, cfg, args[0], opts.Global, opts.Quiet)
@@ -84,8 +84,9 @@ func disconnectClientCommand(cwd string, cfg client.Config) *cobra.Command {
 
 func manualClientCommand() *cobra.Command {
 	cmd := &cobra.Command{
-		Use:  "manual-instructions",
-		Args: cobra.NoArgs,
+		Use:   "manual-instructions",
+		Short: "Display the manual instructions to connect the MCP client",
+		Args:  cobra.NoArgs,
 		RunE: func(cmd *cobra.Command, _ []string) error {
 			printAsJSON, err := cmd.Flags().GetBool("json")
 			if err != nil {

cmd/docker-mcp/commands/gateway.go

@@ -86,14 +86,14 @@ func gatewayCommand(docker docker.Client) *cobra.Command {
 		},
 	}
 
-	runCmd.Flags().StringSliceVar(&options.ServerNames, "servers", nil, "names of the servers to enable (if non empty, ignore --registry flag)")
-	runCmd.Flags().StringSliceVar(&options.CatalogPath, "catalog", options.CatalogPath, "paths to docker catalogs (absolute or relative to ~/.docker/mcp/catalogs/)")
-	runCmd.Flags().StringSliceVar(&additionalCatalogs, "additional-catalog", nil, "additional catalog paths to append to the default catalogs")
-	runCmd.Flags().StringSliceVar(&options.RegistryPath, "registry", options.RegistryPath, "paths to the registry files (absolute or relative to ~/.docker/mcp/)")
-	runCmd.Flags().StringSliceVar(&additionalRegistries, "additional-registry", nil, "additional registry paths to merge with the default registry.yaml")
-	runCmd.Flags().StringSliceVar(&options.ConfigPath, "config", options.ConfigPath, "paths to the config files (absolute or relative to ~/.docker/mcp/)")
-	runCmd.Flags().StringSliceVar(&additionalConfigs, "additional-config", nil, "additional config paths to merge with the default config.yaml")
-	runCmd.Flags().StringVar(&options.SecretsPath, "secrets", options.SecretsPath, "colon separated paths to search for secrets. Can be `docker-desktop` or a path to a .env file (default to using Docker Deskop's secrets API)")
+	runCmd.Flags().StringSliceVar(&options.ServerNames, "servers", nil, "Names of the servers to enable (if non empty, ignore --registry flag)")
+	runCmd.Flags().StringSliceVar(&options.CatalogPath, "catalog", options.CatalogPath, "Paths to docker catalogs (absolute or relative to ~/.docker/mcp/catalogs/)")
+	runCmd.Flags().StringSliceVar(&additionalCatalogs, "additional-catalog", nil, "Additional catalog paths to append to the default catalogs")
+	runCmd.Flags().StringSliceVar(&options.RegistryPath, "registry", options.RegistryPath, "Paths to the registry files (absolute or relative to ~/.docker/mcp/)")
+	runCmd.Flags().StringSliceVar(&additionalRegistries, "additional-registry", nil, "Additional registry paths to merge with the default registry.yaml")
+	runCmd.Flags().StringSliceVar(&options.ConfigPath, "config", options.ConfigPath, "Paths to the config files (absolute or relative to ~/.docker/mcp/)")
+	runCmd.Flags().StringSliceVar(&additionalConfigs, "additional-config", nil, "Additional config paths to merge with the default config.yaml")
+	runCmd.Flags().StringVar(&options.SecretsPath, "secrets", options.SecretsPath, "Colon separated paths to search for secrets. Can be `docker-desktop` or a path to a .env file (default to using Docker Desktop's secrets API)")
 	runCmd.Flags().StringSliceVar(&options.ToolNames, "tools", options.ToolNames, "List of tools to enable")
 	runCmd.Flags().StringArrayVar(&options.Interceptors, "interceptor", options.Interceptors, "List of interceptors to use (format: when:type:path, e.g. 'before:exec:/bin/path')")
 	runCmd.Flags().IntVar(&options.Port, "port", options.Port, "TCP port to listen on (default is to listen on stdio)")

cmd/docker-mcp/commands/oauth.go

@@ -36,8 +36,9 @@ func lsOauthCommand() *cobra.Command {
 
 func authorizeOauthCommand() *cobra.Command {
 	return &cobra.Command{
-		Use:  "authorize <app>",
-		Args: cobra.ExactArgs(1),
+		Use:   "authorize <app>",
+		Short: "Authorize the specified OAuth app.",
+		Args:  cobra.ExactArgs(1),
 		RunE: func(cmd *cobra.Command, args []string) error {
 			return oauth.Authorize(cmd.Context(), args[0])
 		},
@@ -46,8 +47,9 @@ func authorizeOauthCommand() *cobra.Command {
 
 func revokeOauthCommand() *cobra.Command {
 	return &cobra.Command{
-		Use:  "revoke <app>",
-		Args: cobra.ExactArgs(1),
+		Use:   "revoke <app>",
+		Args:  cobra.ExactArgs(1),
+		Short: "Revoke the specified OAuth app.",
 		RunE: func(cmd *cobra.Command, args []string) error {
 			return oauth.Revoke(cmd.Context(), args[0])
 		},

cmd/docker-mcp/commands/policy.go

@@ -11,13 +11,13 @@ import (
 )
 
 const setPolicyExample = `
-# Backup the current policy to a file
+### Backup the current policy to a file
 docker mcp policy dump > policy.conf
 
-# Set a new policy
+### Set a new policy
 docker mcp policy set "my-secret allows postgres"
 
-# Restore the previous policy
+### Restore the previous policy
 cat policy.conf | docker mcp policy set
 `
 

cmd/docker-mcp/commands/root.go

@@ -33,6 +33,7 @@ Examples:
 func Root(ctx context.Context, cwd string, dockerCli command.Cli) *cobra.Command {
 	cmd := &cobra.Command{
 		Use:              "mcp [OPTIONS]",
+		Short:            "Manage MCP servers and clients",
 		TraverseChildren: true,
 		CompletionOptions: cobra.CompletionOptions{
 			DisableDefaultCmd: false,

cmd/docker-mcp/commands/secret.go

@@ -12,13 +12,15 @@ import (
 )
 
 const setSecretExample = `
-# Using secrets for postgres password with default policy:
-docker mcp secret set POSTGRES_PASSWORD=my-secret-password
-docker run -d -l x-secret:POSTGRES_PASSWORD=/pwd.txt -e POSTGRES_PASSWORD_FILE=/pwd.txt -p 5432 postgres
+### Use secrets for postgres password with default policy
 
-# Or pass the secret via STDIN:
-echo my-secret-password > pwd.txt
-cat pwd.txt | docker mcp secret set POSTGRES_PASSWORD
+> docker mcp secret set POSTGRES_PASSWORD=my-secret-password
+> docker run -d -l x-secret:POSTGRES_PASSWORD=/pwd.txt -e POSTGRES_PASSWORD_FILE=/pwd.txt -p 5432 postgres
+
+### Pass the secret via STDIN
+
+> echo my-secret-password > pwd.txt
+> cat pwd.txt | docker mcp secret set POSTGRES_PASSWORD
 `
 
 func secretCommand(docker docker.Client) *cobra.Command {

cmd/docker-mcp/commands/server.go

@@ -22,7 +22,7 @@ func serverCommand(docker docker.Client) *cobra.Command {
 	lsCommand := &cobra.Command{
 		Use:     "list",
 		Aliases: []string{"ls"},
-		Short:   "list enabled servers",
+		Short:   "List enabled servers",
 		Args:    cobra.NoArgs,
 		RunE: func(cmd *cobra.Command, _ []string) error {
 			list, err := server.List(cmd.Context(), docker)

cmd/docker-mcp/commands/tools.go

@@ -26,7 +26,7 @@ func toolsCommand() *cobra.Command {
 	cmd.AddCommand(&cobra.Command{
 		Use:     "list",
 		Aliases: []string{"ls"},
-		Short:   "list tools",
+		Short:   "List tools",
 		Args:    cobra.NoArgs,
 		RunE: func(cmd *cobra.Command, _ []string) error {
 			return tools.List(cmd.Context(), version, gatewayArgs, verbose, "list", "", format)
@@ -35,7 +35,7 @@ func toolsCommand() *cobra.Command {
 
 	cmd.AddCommand(&cobra.Command{
 		Use:   "count",
-		Short: "count tools",
+		Short: "Count tools",
 		Args:  cobra.NoArgs,
 		RunE: func(cmd *cobra.Command, _ []string) error {
 			return tools.List(cmd.Context(), version, gatewayArgs, verbose, "count", "", format)
@@ -44,15 +44,15 @@ func toolsCommand() *cobra.Command {
 
 	cmd.AddCommand(&cobra.Command{
 		Use:   "inspect",
-		Short: "inspect a tool",
+		Short: "Inspect a tool",
 		Args:  cobra.ExactArgs(1),
 		RunE: func(cmd *cobra.Command, args []string) error {
 			return tools.List(cmd.Context(), version, gatewayArgs, verbose, "inspect", args[0], format)
 		},
 	})
 	cmd.AddCommand(&cobra.Command{
 		Use:   "call",
-		Short: "call a tool",
+		Short: "Call a tool",
 		RunE: func(cmd *cobra.Command, args []string) error {
 			return tools.Call(cmd.Context(), version, gatewayArgs, verbose, args)
 		},

docs/generator/reference/docker_mcp.yaml

@@ -1,4 +1,11 @@
 command: docker mcp
+short: Manage MCP servers and clients
+long: |-
+    The MCP Gateway is Docker's open-source enterprise solution for orchestrating
+    Model Context Protocol (MCP) servers and clients.
+
+    For more information see [Docker MCP](/ai/mcp-gateway/) and
+    the public [GitHub repository](https://github.com/docker/mcp-gateway).
 pname: docker
 plink: docker.yaml
 cname:

docs/generator/reference/docker_mcp_client_connect.yaml

@@ -1,6 +1,8 @@
 command: docker mcp client connect
-short: Connect the Docker MCP Toolkit to a client
-long: Connect the Docker MCP Toolkit to a client
+short: |
+    Connect the Docker MCP Toolkit to a client. Supported clients: claude-desktop continue cursor gemini goose gordon lmstudio sema4 vscode
+long: |
+    Connect the Docker MCP Toolkit to a client. Supported clients: claude-desktop continue cursor gemini goose gordon lmstudio sema4 vscode
 usage: |-
     docker mcp client connect [OPTIONS] <mcp-client>
 

docs/generator/reference/docker_mcp_client_disconnect.yaml

@@ -1,6 +1,8 @@
 command: docker mcp client disconnect
-short: Disconnect the Docker MCP Toolkit from a client
-long: Disconnect the Docker MCP Toolkit from a client
+short: |
+    Disconnect the Docker MCP Toolkit from a client. Supported clients: claude-desktop continue cursor gemini goose gordon lmstudio sema4 vscode
+long: |
+    Disconnect the Docker MCP Toolkit from a client. Supported clients: claude-desktop continue cursor gemini goose gordon lmstudio sema4 vscode
 usage: |-
     docker mcp client disconnect [OPTIONS] <mcp-client>
 

docs/generator/reference/docker_mcp_client_manual-instructions.yaml

@@ -1,4 +1,6 @@
 command: docker mcp client manual-instructions
+short: Display the manual instructions to connect the MCP client
+long: Display the manual instructions to connect the MCP client
 usage: docker mcp client manual-instructions
 pname: docker mcp client
 plink: docker_mcp_client.yaml

docs/generator/reference/docker_mcp_gateway_run.yaml

@@ -8,7 +8,7 @@ options:
     - option: additional-catalog
       value_type: stringSlice
       default_value: '[]'
-      description: additional catalog paths to append to the default catalogs
+      description: Additional catalog paths to append to the default catalogs
       deprecated: false
       hidden: false
       experimental: false
@@ -18,7 +18,7 @@ options:
     - option: additional-config
       value_type: stringSlice
       default_value: '[]'
-      description: additional config paths to merge with the default config.yaml
+      description: Additional config paths to merge with the default config.yaml
       deprecated: false
       hidden: false
       experimental: false
@@ -28,7 +28,7 @@ options:
     - option: additional-registry
       value_type: stringSlice
       default_value: '[]'
-      description: additional registry paths to merge with the default registry.yaml
+      description: Additional registry paths to merge with the default registry.yaml
       deprecated: false
       hidden: false
       experimental: false
@@ -59,7 +59,7 @@ options:
       value_type: stringSlice
       default_value: '[docker-mcp.yaml]'
       description: |
-        paths to docker catalogs (absolute or relative to ~/.docker/mcp/catalogs/)
+        Paths to docker catalogs (absolute or relative to ~/.docker/mcp/catalogs/)
       deprecated: false
       hidden: false
       experimental: false
@@ -79,7 +79,7 @@ options:
     - option: config
       value_type: stringSlice
       default_value: '[config.yaml]'
-      description: paths to the config files (absolute or relative to ~/.docker/mcp/)
+      description: Paths to the config files (absolute or relative to ~/.docker/mcp/)
       deprecated: false
       hidden: false
       experimental: false
@@ -173,7 +173,7 @@ options:
       value_type: stringSlice
       default_value: '[registry.yaml]'
       description: |
-        paths to the registry files (absolute or relative to ~/.docker/mcp/)
+        Paths to the registry files (absolute or relative to ~/.docker/mcp/)
       deprecated: false
       hidden: false
       experimental: false
@@ -184,7 +184,7 @@ options:
       value_type: string
       default_value: docker-desktop
       description: |
-        colon separated paths to search for secrets. Can be `docker-desktop` or a path to a .env file (default to using Docker Deskop's secrets API)
+        Colon separated paths to search for secrets. Can be `docker-desktop` or a path to a .env file (default to using Docker Desktop's secrets API)
       deprecated: false
       hidden: false
       experimental: false
@@ -195,7 +195,7 @@ options:
       value_type: stringSlice
       default_value: '[]'
       description: |
-        names of the servers to enable (if non empty, ignore --registry flag)
+        Names of the servers to enable (if non empty, ignore --registry flag)
       deprecated: false
       hidden: false
       experimental: false

docs/generator/reference/docker_mcp_oauth_authorize.yaml

@@ -1,4 +1,6 @@
 command: docker mcp oauth authorize
+short: Authorize the specified OAuth app.
+long: Authorize the specified OAuth app.
 usage: docker mcp oauth authorize <app>
 pname: docker mcp oauth
 plink: docker_mcp_oauth.yaml

docs/generator/reference/docker_mcp_oauth_revoke.yaml

@@ -1,4 +1,6 @@
 command: docker mcp oauth revoke
+short: Revoke the specified OAuth app.
+long: Revoke the specified OAuth app.
 usage: docker mcp oauth revoke <app>
 pname: docker mcp oauth
 plink: docker_mcp_oauth.yaml

docs/generator/reference/docker_mcp_policy_set.yaml

@@ -5,13 +5,13 @@ usage: docker mcp policy set <content>
 pname: docker mcp policy
 plink: docker_mcp_policy.yaml
 examples: |-
-    # Backup the current policy to a file
+    ### Backup the current policy to a file
     docker mcp policy dump > policy.conf
 
-    # Set a new policy
+    ### Set a new policy
     docker mcp policy set "my-secret allows postgres"
 
-    # Restore the previous policy
+    ### Restore the previous policy
     cat policy.conf | docker mcp policy set
 deprecated: false
 hidden: false

docs/generator/reference/docker_mcp_secret.yaml

@@ -12,13 +12,15 @@ clink:
     - docker_mcp_secret_rm.yaml
     - docker_mcp_secret_set.yaml
 examples: |-
-    # Using secrets for postgres password with default policy:
-    docker mcp secret set POSTGRES_PASSWORD=my-secret-password
-    docker run -d -l x-secret:POSTGRES_PASSWORD=/pwd.txt -e POSTGRES_PASSWORD_FILE=/pwd.txt -p 5432 postgres
+    ### Use secrets for postgres password with default policy
 
-    # Or pass the secret via STDIN:
-    echo my-secret-password > pwd.txt
-    cat pwd.txt | docker mcp secret set POSTGRES_PASSWORD
+    > docker mcp secret set POSTGRES_PASSWORD=my-secret-password
+    > docker run -d -l x-secret:POSTGRES_PASSWORD=/pwd.txt -e POSTGRES_PASSWORD_FILE=/pwd.txt -p 5432 postgres
+
+    ### Pass the secret via STDIN
+
+    > echo my-secret-password > pwd.txt
+    > cat pwd.txt | docker mcp secret set POSTGRES_PASSWORD
 deprecated: false
 hidden: false
 experimental: false

docs/generator/reference/docker_mcp_secret_set.yaml

@@ -15,13 +15,19 @@ options:
       kubernetes: false
       swarm: false
 examples: |-
-    # Using secrets for postgres password with default policy:
+    ### Use secrets for postgres password with default policy
+
+    ```console
     docker mcp secret set POSTGRES_PASSWORD=my-secret-password
     docker run -d -l x-secret:POSTGRES_PASSWORD=/pwd.txt -e POSTGRES_PASSWORD_FILE=/pwd.txt -p 5432 postgres
+    ```
+
+    ### Pass the secret via STDIN
 
-    # Or pass the secret via STDIN:
+    ```console
     echo my-secret-password > pwd.txt
     cat pwd.txt | docker mcp secret set POSTGRES_PASSWORD
+    ```
 deprecated: false
 hidden: false
 experimental: false

docs/generator/reference/docker_mcp_server_list.yaml

@@ -1,7 +1,7 @@
 command: docker mcp server list
 aliases: docker mcp server list, docker mcp server ls
-short: list enabled servers
-long: list enabled servers
+short: List enabled servers
+long: List enabled servers
 usage: docker mcp server list
 pname: docker mcp server
 plink: docker_mcp_server.yaml

docs/generator/reference/docker_mcp_tools_call.yaml

@@ -1,6 +1,6 @@
 command: docker mcp tools call
-short: call a tool
-long: call a tool
+short: Call a tool
+long: Call a tool
 usage: docker mcp tools call
 pname: docker mcp tools
 plink: docker_mcp_tools.yaml

docs/generator/reference/docker_mcp_tools_count.yaml

@@ -1,6 +1,6 @@
 command: docker mcp tools count
-short: count tools
-long: count tools
+short: Count tools
+long: Count tools
 usage: docker mcp tools count
 pname: docker mcp tools
 plink: docker_mcp_tools.yaml

docs/generator/reference/docker_mcp_tools_inspect.yaml

@@ -1,6 +1,6 @@
 command: docker mcp tools inspect
-short: inspect a tool
-long: inspect a tool
+short: Inspect a tool
+long: Inspect a tool
 usage: docker mcp tools inspect
 pname: docker mcp tools
 plink: docker_mcp_tools.yaml