1# Generating Markdown Docs For Your Own cobra.Command
2
3Generating Markdown pages from a cobra command is incredibly easy. An example is as follows:
4
5```go
6package main
7
8import (
9 "log"
10
11 "github.com/spf13/cobra"
12 "github.com/spf13/cobra/doc"
13)
14
15func main() {
16 cmd := &cobra.Command{
17 Use: "test",
18 Short: "my test program",
19 }
20 err := doc.GenMarkdownTree(cmd, "/tmp")
21 if err != nil {
22 log.Fatal(err)
23 }
24}
25```
26
27That will get you a Markdown document `/tmp/test.md`
28
29## Generate markdown docs for the entire command tree
30
31This program can actually generate docs for the kubectl command in the kubernetes project
32
33```go
34package main
35
36import (
37 "log"
38 "io/ioutil"
39 "os"
40
41 "k8s.io/kubernetes/pkg/kubectl/cmd"
42 cmdutil "k8s.io/kubernetes/pkg/kubectl/cmd/util"
43
44 "github.com/spf13/cobra/doc"
45)
46
47func main() {
48 kubectl := cmd.NewKubectlCommand(cmdutil.NewFactory(nil), os.Stdin, ioutil.Discard, ioutil.Discard)
49 err := doc.GenMarkdownTree(kubectl, "./")
50 if err != nil {
51 log.Fatal(err)
52 }
53}
54```
55
56This will generate a whole series of files, one for each command in the tree, in the directory specified (in this case "./")
57
58## Generate markdown docs for a single command
59
60You may wish to have more control over the output, or only generate for a single command, instead of the entire command tree. If this is the case you may prefer to `GenMarkdown` instead of `GenMarkdownTree`
61
62```go
63 out := new(bytes.Buffer)
64 err := doc.GenMarkdown(cmd, out)
65 if err != nil {
66 log.Fatal(err)
67 }
68```
69
70This will write the markdown doc for ONLY "cmd" into the out, buffer.
71
72## Customize the output
73
74Both `GenMarkdown` and `GenMarkdownTree` have alternate versions with callbacks to get some control of the output:
75
76```go
77func GenMarkdownTreeCustom(cmd *Command, dir string, filePrepender, linkHandler func(string) string) error {
78 //...
79}
80```
81
82```go
83func GenMarkdownCustom(cmd *Command, out *bytes.Buffer, linkHandler func(string) string) error {
84 //...
85}
86```
87
88The `filePrepender` will prepend the return value given the full filepath to the rendered Markdown file. A common use case is to add front matter to use the generated documentation with [Hugo](https://gohugo.io/):
89
90```go
91const fmTemplate = `---
92date: %s
93title: "%s"
94slug: %s
95url: %s
96---
97`
98
99filePrepender := func(filename string) string {
100 now := time.Now().Format(time.RFC3339)
101 name := filepath.Base(filename)
102 base := strings.TrimSuffix(name, path.Ext(name))
103 url := "/commands/" + strings.ToLower(base) + "/"
104 return fmt.Sprintf(fmTemplate, now, strings.Replace(base, "_", " ", -1), base, url)
105}
106```
107
108The `linkHandler` can be used to customize the rendered internal links to the commands, given a filename:
109
110```go
111linkHandler := func(name string) string {
112 base := strings.TrimSuffix(name, path.Ext(name))
113 return "/commands/" + strings.ToLower(base) + "/"
114}
115```
View as plain text