more examples and polisihing of markdown doc based of feedback from Sylvia Pffeifer