markdown and nice formatting
clean up YAML and modify some descriptions