feat: add embedded usage markdown files for version commands

Author: osterman

cmd/version/list.go

@@ -1,6 +1,7 @@
 package version
 
 import (
+	_ "embed"
 	"fmt"
 	"os"
 	"strings"
@@ -15,6 +16,9 @@ import (
 	errUtils "github.com/cloudposse/atmos/errors"
 )
 
+//go:embed markdown/atmos_version_list_usage.md
+var listUsageMarkdown string
+
 const (
 	listDefaultLimit = 10
 	listMaxLimit     = 100
@@ -110,26 +114,10 @@ func fetchReleasesWithSpinner(client GitHubClient, opts ReleaseOptions) ([]*gith
 }
 
 var listCmd = &cobra.Command{
-	Use:   "list",
-	Short: "List Atmos releases",
-	Long:  `List available Atmos releases from GitHub with pagination and filtering options.`,
-	Example: `  # List the last 10 releases (default)
-  atmos version list
-
-  # List the last 20 releases
-  atmos version list --limit 20
-
-  # List releases starting from offset 10
-  atmos version list --offset 10
-
-  # Include pre-releases
-  atmos version list --include-prereleases
-
-  # List releases since a specific date
-  atmos version list --since 2025-01-01
-
-  # Output as JSON
-  atmos version list --format json`,
+	Use:     "list",
+	Short:   "List Atmos releases",
+	Long:    `List available Atmos releases from GitHub with pagination and filtering options.`,
+	Example: listUsageMarkdown,
 	RunE: func(cmd *cobra.Command, args []string) error {
 		// Validate limit.
 		if listLimit < 1 || listLimit > listMaxLimit {

cmd/version/markdown/atmos_version_list_usage.md

@@ -0,0 +1,47 @@
+- List the last 10 releases (default)
+
+```
+$ atmos version list
+```
+
+- List the last 20 releases
+
+```
+$ atmos version list --limit 20
+```
+
+- List releases starting from offset 10
+
+```
+$ atmos version list --offset 10
+```
+
+- Include pre-releases
+
+```
+$ atmos version list --include-prereleases
+```
+
+- List releases since a specific date
+
+```
+$ atmos version list --since 2025-01-01
+```
+
+- Output as JSON
+
+```
+$ atmos version list --format json
+```
+
+- Output as YAML
+
+```
+$ atmos version list --format yaml
+```
+
+- Combine multiple options
+
+```
+$ atmos version list --limit 5 --include-prereleases --format json
+```

cmd/version/markdown/atmos_version_show_usage.md

@@ -0,0 +1,29 @@
+- Show details for the latest release
+
+```
+$ atmos version show
+```
+
+- Show details for a specific version
+
+```
+$ atmos version show v1.194.0
+```
+
+- Show details without the 'v' prefix
+
+```
+$ atmos version show 1.194.0
+```
+
+- Output as JSON
+
+```
+$ atmos version show v1.194.0 --format json
+```
+
+- Output as YAML
+
+```
+$ atmos version show v1.194.0 --format yaml
+```

cmd/version/show.go

@@ -1,6 +1,7 @@
 package version
 
 import (
+	_ "embed"
 	"fmt"
 	"os"
 	"strings"
@@ -14,6 +15,9 @@ import (
 	errUtils "github.com/cloudposse/atmos/errors"
 )
 
+//go:embed markdown/atmos_version_show_usage.md
+var showUsageMarkdown string
+
 var showFormat string
 
 type showModel struct {
@@ -116,20 +120,17 @@ func fetchReleaseWithSpinner(client GitHubClient, versionArg string) (*github.Re
 }
 
 var showCmd = &cobra.Command{
-	Use:   "show <version>",
-	Short: "Show details for a specific Atmos release",
-	Long:  `Display detailed information about a specific Atmos release including release notes and download links.`,
-	Example: `  # Show details for a specific version
-  atmos version show v1.95.0
-
-  # Show details for the latest release
-  atmos version show latest
-
-  # Output as JSON
-  atmos version show v1.95.0 --format json`,
-	Args: cobra.ExactArgs(1),
+	Use:     "show [version]",
+	Short:   "Show details for a specific Atmos release",
+	Long:    `Display detailed information about a specific Atmos release including release notes and download links.`,
+	Example: showUsageMarkdown,
+	Args:    cobra.MaximumNArgs(1),
 	RunE: func(cmd *cobra.Command, args []string) error {
-		versionArg := args[0]
+		// Default to latest if no version specified.
+		versionArg := ""
+		if len(args) > 0 {
+			versionArg = args[0]
+		}
 
 		// Create GitHub client.
 		client := &RealGitHubClient{}