Luke Evers

Getting Started with Literate Go

Posted on 2 August 2016

You might be wondering what "Literate Go" is, although it's possible you can figure it out just by the name alone. Literate Go is a project of mine that I made over the weekend to play around with the idea of literate programming with the Go programming language.


It's a fair question.

I've been really interested in literate programming for a year or so, but haven't done any. I was really amazed when I saw this file in a C to Rust translator that was written in Haskell that I found from this Hacker News comment.

How does it work?

As of right now, it's extremely simple. Instead of writing normal source files, you write in a markdown-style with actual Go code in triple back-tick blocks. You may, if you so wish, set a language or comment at the end of each triple back-tick. If you're hosting your code somewhere like GitHub that renders with syntax support, you might want to set the language in each block to be go like this:

package main


I wrote a CLI written in Go that does the basic implementation of my version of "Literate Go" that you can use to both compile and build your lgo files.

   lgo - literate go

   lgo [global options] command [command options] [arguments...]


     build    compile lgo files and build go files
     compile  compile lgo files to go files
     help, h  Shows a list of commands or help for one command

   --help, -h     show help
   --version, -v  print the version

If you wish to write your files in a different format (.md for example if you want that syntax highlighting where places support it), you can specify it both on compile and build:

--extension md, --ext md  file extensions to parse (default: "lgo") [$FILE_EXT]

Future plans

I only have a few ideas in mind at the current time. I haven't used lgo on any actual projects yet, only a few examples in the repository to play around with it. More ideas will come as I continue to test/play with this.

  • Actual error handling
  • Importing a dependency at any time
  • Pseudocode blocks (code blocks that don't get compiled)

Check it out

You can view the code (which is both the implementation and the spec) on GitHub at lukevers/lgo.

comments powered by Disqus