move to markdown. add some more explanations