Produce readable source code listings for Go source files.
Switch branches/tags
Nothing to show
Clone or download
Fetching latest commit…
Cannot retrieve the latest commit at this time.
Type Name Latest commit message Commit time
Failed to load latest commit information.


golst is a Go command line tool for generating readable program listings. It was inspired by Luke Gorries' post "Readable Programs" and, in particular, his pbook example.

Listings that are written to a file are written as <file.go>.<format>; for example, producing listings for listing.go:

  • markdown ->
  • HTML -> listing.go.html
  • PDF -> listing.go.pdf


  • To produce an HTML listing for listing.go:

      golst -o html listing.go

    This will produce listing.go.html, which is a standalone page. The template for this page is contained in the html.go source file, and is taken from my site tyrfingr.

  • To produce a PDF listing for pandoc.go:

      golst -o pdf pandoc.go

    Similar to the previous example, this will produce the PDF file pandoc.go.pdf.

  • To produce a markdown listing for html.go and have this printed to standard output:

      golst html.go

    Or, alternatively,

      golst -o - html.go
  • You can produce listings for multiple files at the same time:

      golst -o pdf *.go

    If you ran this on the golst directory, you would have listing.go.pdf, html.go.pdf, and pandoc.go.pdf.

Supported Output Formats

Standalone listings are generated; the following formats (selected with the -o flag) are supported:

  • html - generate HTML listing
  • latex - uses pandoc to convert the markdown to a LaTeX listing.
  • md - generate markdown listing
  • pdf - uses pandoc to convert the markdown to a PDF listing.
  • tex - rudimentary pure-Go TeX listing.


  • golst uses blackfriday for producing HTML from the listing. This will automatically be pulled in by go get.

  • pandoc is required for conversion to PDF.


golst is released under an ISC license. For details, see LICENSE in the source repository.