Improve README

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?

Start with the README and the current godocdown-based generation approach described in the issue. Compare the stated capabilities and limitations of godocdown and goreadme, then determine whether curated Markdown documentation is preferable. Done means the project has a decided documentation approach and the README workflow reflects it.

Written by the indexing model from the issue text.