Improve README

[frankban]

The README file is generated using godocdown, which is not maintained and doesn't support nice to have features like syntax highlighting of code blocks and table of contents.
There is a much more maintained library (https://github.com/posener/goreadme) that seems to support code highlighting, but lacks the templating features of godocdown.
Should we instead stop generating README from godocs, and prefer more curated markdown documentation?

[frankban]

Conversation started at #96

[gilcrest]

IMO, you should just curate a separate README. You have the extra step of having to add documentation to the doc.go file anyway, so just editing the README directly doesn't seem that much of an extra burden. Plus, markdown is pretty fun to write compared to just bland old text. The README can be a bit better organized and can teach the end-user a bit more if crafted properly.

[dolmen]

About godocdown, are you talking about https://github.com/robertkrimen/godocdown which didn't got a commit for 10 years now?

Note also that godocdown doesn't support modern go doc features such as godoc links. This keeps the project is the old world.

[dolmen]

pkg.go.dev is so good now that I think that duplicating the Go documentation in the README is useless as every Go developer should now be aware of it. Anyway I've rebuilt README with godocdown in #162.