Comment 1:

there are existing tools to do 3. e.g.
https://groups.google.com/forum/#!topic/golang-nuts/wGNwttzl19Y
I think converting doc to README.md for github is pretty
common among github projects, so we don't need to do 1 as the
converted markdown docs will be duplication anyway.
It feels like option 2 reverses the information flow, as we
should recommend idiomatic and accurate docs in Go source code
instead of writing docs in markdown files first and then importing
into Go source.

Comment 2:

4) fix github

Comment 3:

I prefer to keep the two things unrelated by any automatic means. I use READMEs that are
basically just a link to the relevant godoc.org page.

I'd like to see a godoc html output -> md file generator in some form.
(Probably directly, not by parsing the html.)

Still missing this. This or at least properly working #2381
Right now it's really difficult to produce nice documents for internal/private tools.

I might take a stab at this (option 3) - are there any available docs on the structure of the plaintext output of godoc so I don't need to do this by trial and error as I encounter new sections? Also, as per #2381 (comment), how should dependencies be linked together?

EDIT: Scratch that, looks like I've been beaten

Is this issue still relevant given that https://pkg.go.dev shows the readme.md file for modules?