Gocco is a Go port of Docco: the original quick-and-dirty, hundred-line-long, literate-programming-style documentation generator. It produces HTML that displays your comments alongside your code. Comments are passed through Markdown, and code is passed through Pygments syntax highlighting. This page is the result of running Gocco against its own source file.

If you install Gocco, you can run it from the command-line:

gocco *.go

…will generate an HTML documentation page for each of the named source files, with a menu linking to the other pages, saving it into a docs folder.

The source for Gocco is available on GitHub, and released under the MIT license.

To install Gocco, first make sure you have Pygments Then, with the go tool:

go get github.com/nikhilm/gocco
package main

import (


Due to Go’s statically typed nature, what is passed around in object literals in Docco, requires various structures

A Section captures a piece of documentation and code Every time interleaving code is found between two comments a new Section is created.

type Section struct {
	docsText []byte
	codeText []byte
	DocsHTML []byte
	CodeHTML []byte

a TemplateSection is a section that can be passed to Go’s templating system, which expects strings.

type TemplateSection struct {
	DocsHTML string
	CodeHTML string

The Index field is used to create anchors to sections

	Index int

a Language describes a programming language

type Language struct {

the Pygments name of the language

	name string

The comment delimiter

	symbol string

The regular expression to match the comment delimiter

	commentMatcher *regexp.Regexp

Used as a placeholder so we can parse back Pygments output and put the sections together

	dividerText string

The HTML equivalent

	dividerHTML *regexp.Regexp

a TemplateData is per-file

type TemplateData struct {

Title of the HTML output

	Title string

The Sections making up this file

	Sections []*TemplateSection

A full list of source files so that a table-of-contents can be generated

	Sources []string

Only generate the TOC is there is more than one file Go’s templating system does not allow expressions in the template, so calculate it outside

	Multiple bool

a map of all the languages we know

var languages map[string]*Language

paths of all the source files, sorted

var sources []string

absolute path to get resources

var packageLocation string

Wrap the code in these

const highlightStart = "<div class=\"highlight\"><pre>"
const highlightEnd = "</pre></div>"

Main documentation generation functions

Generate the documentation for a single source file by splitting it into sections, highlighting each section and putting it together. The WaitGroup is used to signal we are done, so that the main goroutine waits for all the sub goroutines

func generateDocumentation(source string, wg *sync.WaitGroup) {
	code, err := ioutil.ReadFile(source)
	if err != nil {
	sections := parse(source, code)
	highlight(source, sections)
	generateHTML(source, sections)

Parse splits code into Sections

func parse(source string, code []byte) *list.List {
	lines := bytes.Split(code, []byte("\n"))
	sections := new(list.List)
	language := getLanguage(source)

	var hasCode bool
	var codeText = new(bytes.Buffer)
	var docsText = new(bytes.Buffer)

save a new section

	save := func(docs, code []byte) {

deep copy the slices since slices always refer to the same storage by default

		docsCopy, codeCopy := make([]byte, len(docs)), make([]byte, len(code))
		copy(docsCopy, docs)
		copy(codeCopy, code)
		sections.PushBack(&Section{docsCopy, codeCopy, nil, nil})

	for _, line := range lines {

if the line is a comment

		if language.commentMatcher.Match(line) {

but there was previous code

			if hasCode {

we need to save the existing documentation and text as a section and start a new section since code blocks have to be delimited before being sent to Pygments

				save(docsText.Bytes(), codeText.Bytes())
				hasCode = false
			docsText.Write(language.commentMatcher.ReplaceAll(line, nil))
		} else {
			hasCode = true

save any remaining parts of the source file

	save(docsText.Bytes(), codeText.Bytes())
	return sections

highlight pipes the source to Pygments, section by section delimited by dividerText, then reads back the highlighted output, searches for the delimiters and extracts the HTML version of the code and documentation for each Section

func highlight(source string, sections *list.List) {
	language := getLanguage(source)
	pygments := exec.Command("pygmentize", "-l", language.name, "-f", "html", "-O", "encoding=utf-8")
	pygmentsInput, _ := pygments.StdinPipe()
	pygmentsOutput, _ := pygments.StdoutPipe()

start the process before we start piping data to it otherwise the pipe may block

	for e := sections.Front(); e != nil; e = e.Next() {
		if e.Next() != nil {
			io.WriteString(pygmentsInput, language.dividerText)

	buf := new(bytes.Buffer)
	io.Copy(buf, pygmentsOutput)

	output := buf.Bytes()
	output = bytes.Replace(output, []byte(highlightStart), nil, -1)
	output = bytes.Replace(output, []byte(highlightEnd), nil, -1)

	for e := sections.Front(); e != nil; e = e.Next() {
		index := language.dividerHTML.FindIndex(output)
		if index == nil {
			index = []int{len(output), len(output)}

		fragment := output[0:index[0]]
		output = output[index[1]:]
		e.Value.(*Section).CodeHTML = bytes.Join([][]byte{[]byte(highlightStart), []byte(highlightEnd)}, fragment)
		e.Value.(*Section).DocsHTML = blackfriday.MarkdownCommon(e.Value.(*Section).docsText)

compute the output location (in docs/) for the file

func destination(source string) string {
	base := filepath.Base(source)
	return "docs/" + base[0:strings.LastIndex(base, filepath.Ext(base))] + ".html"

render the final HTML

func generateHTML(source string, sections *list.List) {
	title := filepath.Base(source)
	dest := destination(source)

convert every Section into corresponding TemplateSection

	sectionsArray := make([]*TemplateSection, sections.Len())
	for e, i := sections.Front(), 0; e != nil; e, i = e.Next(), i+1 {
		var sec = e.Value.(*Section)
		docsBuf := bytes.NewBuffer(sec.DocsHTML)
		codeBuf := bytes.NewBuffer(sec.CodeHTML)
		sectionsArray[i] = &TemplateSection{docsBuf.String(), codeBuf.String(), i + 1}

run through the Go template

	html := goccoTemplate(TemplateData{title, sectionsArray, sources, len(sources) > 1})
	log.Println("gocco: ", source, " -> ", dest)
	ioutil.WriteFile(dest, html, 0644)

func goccoTemplate(data TemplateData) []byte {

this hack is required because ParseFiles doesn’t seem to work properly, always complaining about empty templates

	t, err := template.New("gocco").Funcs(

introduce the two functions that the template needs

			"base":        filepath.Base,
			"destination": destination,
	if err != nil {
	buf := new(bytes.Buffer)
	err = t.Execute(buf, data)
	if err != nil {
	return buf.Bytes()

get a Language given a path

func getLanguage(source string) *Language {
	return languages[filepath.Ext(source)]

make sure docs/ exists

func ensureDirectory(name string) {
	os.MkdirAll(name, 0755)

func setupLanguages() {
	languages = make(map[string]*Language)

you should add more languages here only the first two fields should change, the rest should be nil, "", nil

	languages[".go"] = &Language{"go", "//", nil, "", nil}

func setup() {

create the regular expressions based on the language comment symbol

	for _, lang := range languages {
		lang.commentMatcher, _ = regexp.Compile("^\\s*" + lang.symbol + "\\s?")
		lang.dividerText = "\n" + lang.symbol + "DIVIDER\n"
		lang.dividerHTML, _ = regexp.Compile("\\n*<span class=\"c1?\">" + lang.symbol + "DIVIDER<\\/span>\\n*")

let’s Go!

func main() {

	sources = flag.Args()

	if flag.NArg() <= 0 {

	ioutil.WriteFile("docs/gocco.css", bytes.NewBufferString(Css).Bytes(), 0755)

	wg := new(sync.WaitGroup)
	for _, arg := range flag.Args() {
		go generateDocumentation(arg, wg)