Docs for Official Repo release

Changes and additions for the Official Repo release on Wednesday.
we really should specify which markdown - there are many, and they don't play nicely.