So we created a markdown flavor called Optic Markdown. We want to meet programmers where they already write about code/styles instead of making them write templates in some dsl. Our markdown relies on HTML comment annotations (so they're hidden) to describe the important parts of a piece of code -- it's kind of like pointing out different parts of a snippet and explaining what they do.
We've been working really hard to build tooling around this because the first few versions were hard to learn/use. Would love to hear any feedback you have on the teaching process. We don't think Optic will take off until we get this just right.
