fix: use docs site paths for command reference See also links

cmd/docgen/docgen.go

@@ -34,6 +34,15 @@ import (
 // defaultDocsDirPath is the default value for the <path> argument
 const defaultDocsDirPath = "docs"
 
+// commandsDocsURLPath is the docs site base path for command reference pages.
+// "See also" links must resolve against this path rather than a bare slug.
+const commandsDocsURLPath = "/tools/slack-cli/reference/commands/"
+
+// commandDocsURL returns the docs site link for a command path (e.g. "slack app").
+func commandDocsURL(commandPath string) string {
+	return commandsDocsURLPath + strings.ReplaceAll(commandPath, " ", "_") + "/"
+}
+
 //go:embed errors.tmpl
 var errorsMarkdownTemplate string
 
@@ -196,8 +205,7 @@ func genMarkdownCommand(cmd *cobra.Command, w io.Writer) error {
 		if cmd.HasParent() {
 			parent := cmd.Parent()
 			pname := parent.CommandPath()
-			link := strings.ReplaceAll(pname, " ", "_")
-			fmt.Fprintf(buf, "* [%s](%s)\t - %s\n", pname, link, parent.Short)
+			fmt.Fprintf(buf, "* [%s](%s)\t - %s\n", pname, commandDocsURL(pname), parent.Short)
 			cmd.VisitParents(func(c *cobra.Command) {
 				if c.DisableAutoGenTag {
 					cmd.DisableAutoGenTag = c.DisableAutoGenTag
@@ -217,8 +225,7 @@ func genMarkdownCommand(cmd *cobra.Command, w io.Writer) error {
 				continue
 			}
 			cname := name + " " + child.Name()
-			link := strings.ReplaceAll(cname, " ", "_")
-			fmt.Fprintf(buf, "* [%s](%s)\t - %s\n", cname, link, child.Short)
+			fmt.Fprintf(buf, "* [%s](%s)\t - %s\n", cname, commandDocsURL(cname), child.Short)
 		}
 		fmt.Fprintf(buf, "\n")
 	}

cmd/docgen/docgen_test.go

@@ -15,6 +15,7 @@
 package docgen
 
 import (
+	"bytes"
 	"context"
 	"errors"
 	"path/filepath"
@@ -171,3 +172,47 @@ func TestNewDocsCommand(t *testing.T) {
 		return NewCommand(clients)
 	})
 }
+
+func Test_commandDocsURL(t *testing.T) {
+	tests := map[string]struct {
+		commandPath string
+		expected    string
+	}{
+		"root command": {
+			commandPath: "slack",
+			expected:    "/tools/slack-cli/reference/commands/slack/",
+		},
+		"subcommand replaces spaces with underscores": {
+			commandPath: "slack app",
+			expected:    "/tools/slack-cli/reference/commands/slack_app/",
+		},
+		"nested subcommand": {
+			commandPath: "slack app delete",
+			expected:    "/tools/slack-cli/reference/commands/slack_app_delete/",
+		},
+	}
+	for name, tc := range tests {
+		t.Run(name, func(t *testing.T) {
+			assert.Equal(t, tc.expected, commandDocsURL(tc.commandPath))
+		})
+	}
+}
+
+func Test_genMarkdownCommand(t *testing.T) {
+	root := &cobra.Command{Use: "slack", Short: "Slack command-line tool"}
+	app := &cobra.Command{Use: "app", Short: "App management commands", Run: func(*cobra.Command, []string) {}}
+	del := &cobra.Command{Use: "delete", Short: "Delete the app", Run: func(*cobra.Command, []string) {}}
+	app.AddCommand(del)
+	root.AddCommand(app)
+
+	var buf bytes.Buffer
+	require.NoError(t, genMarkdownCommand(app, &buf))
+	output := buf.String()
+
+	assert.Contains(t, output, "## See also")
+	// Parent link uses the docs site path rather than a bare slug.
+	assert.Contains(t, output, "* [slack](/tools/slack-cli/reference/commands/slack/)")
+	// Child link uses the docs site path rather than a bare slug.
+	assert.Contains(t, output, "* [slack app delete](/tools/slack-cli/reference/commands/slack_app_delete/)")
+	assert.NotContains(t, output, "](slack_app_delete)")
+}

docs/reference/commands/slack.md

@@ -41,34 +41,35 @@ $ slack docs    # Open Slack developer docs
 
 ## See also
 
-* [slack activity](slack_activity)	 - Display the app activity logs from the Slack Platform
-* [slack api](slack_api)	 - Call any Slack API method
-* [slack app](slack_app)	 - Install, uninstall, and list teams with the app installed
-* [slack auth](slack_auth)	 - Add and remove local team authorizations
-* [slack collaborator](slack_collaborator)	 - Manage app collaborators
-* [slack create](slack_create)	 - Create a new Slack project
-* [slack datastore](slack_datastore)	 - Interact with an app's datastore
-* [slack delete](slack_delete)	 - Delete the app
-* [slack deploy](slack_deploy)	 - Deploy the app to the Slack Platform
-* [slack docs](slack_docs)	 - Open Slack developer docs
-* [slack doctor](slack_doctor)	 - Check and report on system and app information
-* [slack env](slack_env)	 - Set, unset, or list environment variables
-* [slack external-auth](slack_external-auth)	 - Adjust settings of external authentication providers
-* [slack feedback](slack_feedback)	 - Share feedback about your experience or project
-* [slack function](slack_function)	 - Manage the functions of an app
-* [slack init](slack_init)	 - Initialize a project to work with the Slack CLI
-* [slack install](slack_install)	 - Install the app to a team
-* [slack list](slack_list)	 - List all authorized accounts
-* [slack login](slack_login)	 - Log in to a Slack account
-* [slack logout](slack_logout)	 - Log out of a team
-* [slack manifest](slack_manifest)	 - Print the app manifest of a project or app
-* [slack platform](slack_platform)	 - Deploy and run apps on the Slack Platform
-* [slack project](slack_project)	 - Create, manage, and doctor a project
-* [slack run](slack_run)	 - Start a local server to develop and run the app locally
-* [slack samples](slack_samples)	 - List available sample apps
-* [slack sandbox](slack_sandbox)	 - Manage developer sandboxes
-* [slack trigger](slack_trigger)	 - List details of existing triggers
-* [slack uninstall](slack_uninstall)	 - Uninstall the app from a team
-* [slack upgrade](slack_upgrade)	 - Checks for available updates to the CLI or SDK
-* [slack version](slack_version)	 - Print the version number
+* [slack activity](/tools/slack-cli/reference/commands/slack_activity/)	 - Display the app activity logs from the Slack Platform
+* [slack api](/tools/slack-cli/reference/commands/slack_api/)	 - Call any Slack API method
+* [slack app](/tools/slack-cli/reference/commands/slack_app/)	 - Install, uninstall, and list teams with the app installed
+* [slack auth](/tools/slack-cli/reference/commands/slack_auth/)	 - Add and remove local team authorizations
+* [slack blocks](/tools/slack-cli/reference/commands/slack_blocks/)	 - Build with Block Kit
+* [slack collaborator](/tools/slack-cli/reference/commands/slack_collaborator/)	 - Manage app collaborators
+* [slack create](/tools/slack-cli/reference/commands/slack_create/)	 - Create a new Slack project
+* [slack datastore](/tools/slack-cli/reference/commands/slack_datastore/)	 - Interact with an app's datastore
+* [slack delete](/tools/slack-cli/reference/commands/slack_delete/)	 - Delete the app
+* [slack deploy](/tools/slack-cli/reference/commands/slack_deploy/)	 - Deploy the app to the Slack Platform
+* [slack docs](/tools/slack-cli/reference/commands/slack_docs/)	 - Open Slack developer docs
+* [slack doctor](/tools/slack-cli/reference/commands/slack_doctor/)	 - Check and report on system and app information
+* [slack env](/tools/slack-cli/reference/commands/slack_env/)	 - Set, unset, or list environment variables
+* [slack external-auth](/tools/slack-cli/reference/commands/slack_external-auth/)	 - Adjust settings of external authentication providers
+* [slack feedback](/tools/slack-cli/reference/commands/slack_feedback/)	 - Share feedback about your experience or project
+* [slack function](/tools/slack-cli/reference/commands/slack_function/)	 - Manage the functions of an app
+* [slack init](/tools/slack-cli/reference/commands/slack_init/)	 - Initialize a project to work with the Slack CLI
+* [slack install](/tools/slack-cli/reference/commands/slack_install/)	 - Install the app to a team
+* [slack list](/tools/slack-cli/reference/commands/slack_list/)	 - List all authorized accounts
+* [slack login](/tools/slack-cli/reference/commands/slack_login/)	 - Log in to a Slack account
+* [slack logout](/tools/slack-cli/reference/commands/slack_logout/)	 - Log out of a team
+* [slack manifest](/tools/slack-cli/reference/commands/slack_manifest/)	 - Print the app manifest of a project or app
+* [slack platform](/tools/slack-cli/reference/commands/slack_platform/)	 - Deploy and run apps on the Slack Platform
+* [slack project](/tools/slack-cli/reference/commands/slack_project/)	 - Create, manage, and doctor a project
+* [slack run](/tools/slack-cli/reference/commands/slack_run/)	 - Start a local server to develop and run the app locally
+* [slack samples](/tools/slack-cli/reference/commands/slack_samples/)	 - List available sample apps
+* [slack sandbox](/tools/slack-cli/reference/commands/slack_sandbox/)	 - Manage developer sandboxes
+* [slack trigger](/tools/slack-cli/reference/commands/slack_trigger/)	 - List details of existing triggers
+* [slack uninstall](/tools/slack-cli/reference/commands/slack_uninstall/)	 - Uninstall the app from a team
+* [slack upgrade](/tools/slack-cli/reference/commands/slack_upgrade/)	 - Checks for available updates to the CLI or SDK
+* [slack version](/tools/slack-cli/reference/commands/slack_version/)	 - Print the version number
 

docs/reference/commands/slack_activity.md

@@ -57,5 +57,5 @@ $ slack platform activity -t  # Continuously poll for new activity logs
 
 ## See also
 
-* [slack](slack)	 - Slack command-line tool
+* [slack](/tools/slack-cli/reference/commands/slack/)	 - Slack command-line tool
 

docs/reference/commands/slack_api.md

@@ -129,5 +129,5 @@ $ slack api views.update view_id=V0123456 view={...}
 
 ## See also
 
-* [slack](slack)	 - Slack command-line tool
+* [slack](/tools/slack-cli/reference/commands/slack/)	 - Slack command-line tool
 

docs/reference/commands/slack_app.md

@@ -45,12 +45,12 @@ $ slack app delete     # Delete an app and app info from a team
 
 ## See also
 
-* [slack](slack)	 - Slack command-line tool
-* [slack app delete](slack_app_delete)	 - Delete the app
-* [slack app install](slack_app_install)	 - Install the app to a team
-* [slack app link](slack_app_link)	 - Add an existing app to the project
-* [slack app list](slack_app_list)	 - List teams with the app installed
-* [slack app settings](slack_app_settings)	 - Open app settings for configurations
-* [slack app uninstall](slack_app_uninstall)	 - Uninstall the app from a team
-* [slack app unlink](slack_app_unlink)	 - Remove a linked app from the project
+* [slack](/tools/slack-cli/reference/commands/slack/)	 - Slack command-line tool
+* [slack app delete](/tools/slack-cli/reference/commands/slack_app_delete/)	 - Delete the app
+* [slack app install](/tools/slack-cli/reference/commands/slack_app_install/)	 - Install the app to a team
+* [slack app link](/tools/slack-cli/reference/commands/slack_app_link/)	 - Add an existing app to the project
+* [slack app list](/tools/slack-cli/reference/commands/slack_app_list/)	 - List teams with the app installed
+* [slack app settings](/tools/slack-cli/reference/commands/slack_app_settings/)	 - Open app settings for configurations
+* [slack app uninstall](/tools/slack-cli/reference/commands/slack_app_uninstall/)	 - Uninstall the app from a team
+* [slack app unlink](/tools/slack-cli/reference/commands/slack_app_unlink/)	 - Remove a linked app from the project
 

docs/reference/commands/slack_app_delete.md

@@ -43,5 +43,5 @@ $ slack app delete --team T0123456 --app local
 
 ## See also
 
-* [slack app](slack_app)	 - Install, uninstall, and list teams with the app installed
+* [slack app](/tools/slack-cli/reference/commands/slack_app/)	 - Install, uninstall, and list teams with the app installed
 

docs/reference/commands/slack_app_install.md

@@ -49,5 +49,5 @@ $ slack app install --team T0123456 --environment local
 
 ## See also
 
-* [slack app](slack_app)	 - Install, uninstall, and list teams with the app installed
+* [slack app](/tools/slack-cli/reference/commands/slack_app/)	 - Install, uninstall, and list teams with the app installed
 

docs/reference/commands/slack_app_link.md

@@ -53,5 +53,5 @@ $ slack app link --team T0123456789 --app A0123456789 --environment deployed
 
 ## See also
 
-* [slack app](slack_app)	 - Install, uninstall, and list teams with the app installed
+* [slack app](/tools/slack-cli/reference/commands/slack_app/)	 - Install, uninstall, and list teams with the app installed
 

docs/reference/commands/slack_app_list.md

@@ -41,5 +41,5 @@ $ slack app list  # List all teams with the app installed
 
 ## See also
 
-* [slack app](slack_app)	 - Install, uninstall, and list teams with the app installed
+* [slack app](/tools/slack-cli/reference/commands/slack_app/)	 - Install, uninstall, and list teams with the app installed
 

docs/reference/commands/slack_app_settings.md

@@ -47,5 +47,5 @@ $ slack app settings --app A0123456789
 
 ## See also
 
-* [slack app](slack_app)	 - Install, uninstall, and list teams with the app installed
+* [slack app](/tools/slack-cli/reference/commands/slack_app/)	 - Install, uninstall, and list teams with the app installed
 

docs/reference/commands/slack_app_uninstall.md

@@ -39,5 +39,5 @@ $ slack app uninstall  # Uninstall an app from a team
 
 ## See also
 
-* [slack app](slack_app)	 - Install, uninstall, and list teams with the app installed
+* [slack app](/tools/slack-cli/reference/commands/slack_app/)	 - Install, uninstall, and list teams with the app installed
 

docs/reference/commands/slack_app_unlink.md

@@ -46,5 +46,5 @@ $ slack app unlink --app A0123456789
 
 ## See also
 
-* [slack app](slack_app)	 - Install, uninstall, and list teams with the app installed
+* [slack app](/tools/slack-cli/reference/commands/slack_app/)	 - Install, uninstall, and list teams with the app installed
 

docs/reference/commands/slack_auth.md

@@ -41,10 +41,10 @@ $ slack auth logout  # Log out of a team
 
 ## See also
 
-* [slack](slack)	 - Slack command-line tool
-* [slack auth list](slack_auth_list)	 - List all authorized accounts
-* [slack auth login](slack_auth_login)	 - Log in to a Slack account
-* [slack auth logout](slack_auth_logout)	 - Log out of a team
-* [slack auth revoke](slack_auth_revoke)	 - Revoke an authentication token
-* [slack auth token](slack_auth_token)	 - Collect a service token
+* [slack](/tools/slack-cli/reference/commands/slack/)	 - Slack command-line tool
+* [slack auth list](/tools/slack-cli/reference/commands/slack_auth_list/)	 - List all authorized accounts
+* [slack auth login](/tools/slack-cli/reference/commands/slack_auth_login/)	 - Log in to a Slack account
+* [slack auth logout](/tools/slack-cli/reference/commands/slack_auth_logout/)	 - Log out of a team
+* [slack auth revoke](/tools/slack-cli/reference/commands/slack_auth_revoke/)	 - Revoke an authentication token
+* [slack auth token](/tools/slack-cli/reference/commands/slack_auth_token/)	 - Collect a service token
 

docs/reference/commands/slack_auth_list.md

@@ -39,5 +39,5 @@ $ slack auth list  # List all authorized accounts
 
 ## See also
 
-* [slack auth](slack_auth)	 - Add and remove local team authorizations
+* [slack auth](/tools/slack-cli/reference/commands/slack_auth/)	 - Add and remove local team authorizations
 

docs/reference/commands/slack_auth_login.md

@@ -52,5 +52,5 @@ $ slack auth login --token xoxp-...
 
 ## See also
 
-* [slack auth](slack_auth)	 - Add and remove local team authorizations
+* [slack auth](/tools/slack-cli/reference/commands/slack_auth/)	 - Add and remove local team authorizations
 

docs/reference/commands/slack_auth_logout.md

@@ -41,5 +41,5 @@ $ slack auth logout --all  # Log out of all team
 
 ## See also
 
-* [slack auth](slack_auth)	 - Add and remove local team authorizations
+* [slack auth](/tools/slack-cli/reference/commands/slack_auth/)	 - Add and remove local team authorizations
 

docs/reference/commands/slack_auth_revoke.md

@@ -39,5 +39,5 @@ $ slack auth revoke --token xoxp-1-4921830...  # Revoke a service token
 
 ## See also
 
-* [slack auth](slack_auth)	 - Add and remove local team authorizations
+* [slack auth](/tools/slack-cli/reference/commands/slack_auth/)	 - Add and remove local team authorizations
 

docs/reference/commands/slack_auth_token.md

@@ -49,5 +49,5 @@ $ slack auth token --challenge 6d0a31c9 --ticket ISQWLiZT0OtMLO3YWNTJO0...
 
 ## See also
 
-* [slack auth](slack_auth)	 - Add and remove local team authorizations
+* [slack auth](/tools/slack-cli/reference/commands/slack_auth/)	 - Add and remove local team authorizations
 

docs/reference/commands/slack_blocks.md

@@ -0,0 +1,45 @@
+# `slack blocks`
+
+Build with Block Kit
+
+## Description
+
+Build layouts using Block Kit and iterate on designs with Block Kit Builder.
+
+```
+slack blocks <subcommand> [flags]
+```
+
+## Flags
+
+```
+  -h, --help   help for blocks
+```
+
+## Global flags
+
+```
+      --accessible           use accessible prompts for screen readers
+  -a, --app string           use a specific app ID or environment
+      --config-dir string    use a custom path for system config directory
+  -e, --experiment strings   use the experiment(s) in the command
+  -f, --force                ignore warnings and continue executing command
+      --no-color             remove styles and formatting from outputs
+  -s, --skip-update          skip checking for latest version of CLI
+  -w, --team string          select workspace or organization by team name or ID
+      --token string         set the access token associated with a team
+  -v, --verbose              print debug logging and additional info
+```
+
+## Examples
+
+```
+# Preview blocks in Block Kit Builder
+$ slack blocks preview --blocks '[{"type":"divider"}]'
+```
+
+## See also
+
+* [slack](/tools/slack-cli/reference/commands/slack/)	 - Slack command-line tool
+* [slack blocks preview](/tools/slack-cli/reference/commands/slack_blocks_preview/)	 - Preview blocks in Block Kit Builder
+

docs/reference/commands/slack_blocks_preview.md

@@ -0,0 +1,56 @@
+# `slack blocks preview`
+
+Preview blocks in Block Kit Builder
+
+## Description
+
+Preview a set of Block Kit blocks with Block Kit Builder in a web browser.
+
+Provide blocks with the --blocks flag.
+The input is a JSON array of blocks or a JSON object with a "blocks" array.
+Pass - to --blocks, or omit all flags, to read from standard input.
+
+```
+slack blocks preview [flags]
+```
+
+## Flags
+
+```
+      --blocks string   blocks to preview as a JSON array or object
+                          (use - to read from standard input)
+  -h, --help            help for preview
+```
+
+## Global flags
+
+```
+      --accessible           use accessible prompts for screen readers
+  -a, --app string           use a specific app ID or environment
+      --config-dir string    use a custom path for system config directory
+  -e, --experiment strings   use the experiment(s) in the command
+  -f, --force                ignore warnings and continue executing command
+      --no-color             remove styles and formatting from outputs
+  -s, --skip-update          skip checking for latest version of CLI
+  -w, --team string          select workspace or organization by team name or ID
+      --token string         set the access token associated with a team
+  -v, --verbose              print debug logging and additional info
+```
+
+## Examples
+
+```
+# Preview blocks passed as a flag value
+$ slack blocks preview --blocks '[{"type":"divider"}]'
+
+# Preview blocks read from a file
+$ slack blocks preview < blocks.json
+
+# Preview blocks read from a redirect and scoped to a team
+$ slack blocks preview --team T0123456 --blocks - < blocks.json
+```
+
+## See also
+
+* [slack blocks](/tools/slack-cli/reference/commands/slack_blocks/)	 - Build with Block Kit
+