Improve README
frankban opened this issue · 4 comments
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?
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.
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.