Where would you recommend putting documentation for a theme?

I’m looking for ways to document a theme. What’s a good balance to strike between the theme’s README.md file and a sample configuration file? As an end-user, the readme seems helpful, especially if it’s going to be prominently displayed on the GitHub site. As the techie, the configuration file calls out to be the primary (it is self-documenting, right?).

In my dearest opinion, if the theme need “configuration” explanation, you can put in in the readme.md in markdown.
With md you’ll have great support (github/gitlab/etc).