docs: touch ups to harmonize rendering on docs website (#76)

* docs: touch ups to harmonize rendering on docs website

* gen docs

* go fmt

Author: ArthurFlag

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>