I'd suggest you, on a purely presentational basis, to just keep the prose in Readme and move examples in separate files. This will allow contributors to easily follow/compare text and markup samples without scrolling the page up and down, and it will also help you track changes in every single section of the project.
I'd suggest you, on a purely presentational basis, to just keep the prose in Readme and move examples in separate files. This will allow contributors to easily follow/compare text and markup samples without scrolling the page up and down, and it will also help you track changes in every single section of the project.