Thoughts on whether we should generate from README.md to docs/ or the other way around? Usually build steps are compositional rather than extracting bits, but people landing on the repo will probably submit edits to README and it would be strange to have part of that file generated, half hand-written.

I've redirected the EDIT THIS DOC buttons on the website to the README.md so we don't get people accidentally submitting changes to the docs files.

Or maybe we should not have so much info in the README and link to docs instead? I know this might be controversial but I think it’s more sane

Yeah that's also an option. We'd have to make sure everything in the README is covered elsewhere though. Babel's README works like this.

@vjeux thoughts on this vs just redirecting from Readme to website and building that out more?

I don't feel strongly about the two variants. Either we redirect to the website or we make sure the two are kept in sync.

Seems more sane to only keep the docs in one place. Better for maintenance and contribution via GitHub (without needing to run build tools). Opened #3139