Format package documentation (godoc) as GitHub friendly Markdown

go get



Command godocdown generates Go documentation in a GitHub-friendly Markdown format.

$ go get

$ godocdown /path/to/package > README.markdown

# Generate documentation for the package/command in the current directory
$ godocdown > README.markdown

# Generate standard Markdown
$ godocdown -plain .

This program is targeted at providing nice-looking documentation for GitHub. With this in mind, it generates GitHub Flavored Markdown ( by default. This can be changed with the use of the "plain" flag to generate standard Markdown.


go get



    Write output to a file instead of stdout
    Write to stdout with -

    The template file to use

    Disable template processing

    Emit standard Markdown, rather than Github Flavored Markdown

    Heading detection method: 1Word, TitleCase, Title, TitleCase1Word, ""
    For each line of the package declaration, godocdown attempts to detect if
    a heading is present via a pattern match. If a heading is detected,
    it prefixes the line with a Markdown heading indicator (typically "###").

    1Word: Only a single word on the entire line

    TitleCase: A line where each word has the first letter capitalized

    Title: A line without punctuation (e.g. a period at the end)

    TitleCase1Word: The line matches either the TitleCase or 1Word pattern


In addition to Markdown rendering, godocdown provides templating via text/template ( for further customization. By putting a file named ".godocdown.template" (or one from the list below) in the same directory as your package/command, godocdown will know to use the file as a template.

# text/template

A template file can also be specified with the "-template" parameter

Along with the standard template functionality, the starting data argument has the following interface:

{{ .Emit }}
// Emit the standard documentation (what godocdown would emit without a template)

{{ .EmitHeader }}
// Emit the package name and an import line (if one is present/needed)

{{ .EmitSynopsis }}
// Emit the package declaration

{{ .EmitUsage }}
// Emit package usage, which includes a constants section, a variables section,
// a functions section, and a types section. In addition, each type may have its own constant,
// variable, and/or function/method listing.

{{ if .IsCommand  }} ... {{ end }}
// A boolean indicating whether the given package is a command or a plain package

{{ .Name }}
// The name of the package/command (string)

{{ .ImportPath }}
// The import path for the package (string)
// (This field will be the empty string if godocdown is unable to guess it)