Markdown is mostly a failure. Yes, it's more convenient than writing your README in docx or txt, but if you want to do anything with it off the narrow beaten path, you'll inevitably have to extend it or give up.

For example, let's say you want something that's not supported by Markdown's syntax, such as dictionary lists, but you want to be able to use Markdown's text formatting syntax with it:

```markdown

<dl>

  <dt>*foo*</dt>

</dl>

```

Most Markdown parsers don't apply Markdown parsing of text nodes within HTML elements. This is why the argument that Markdown supports HTML doesn't work, because it literally doesn't work for why we are using Markdown in the first place... which is to avoid the verbosity of HTML.

This kind of thing really bugs me. No matter what, whenever I've tried using Markdown as a tool for constructing webpages rather than snippets/comments within pages, I end up having to write a custom AST transformer to either get the parser to produce the right output or to prevent it from adding <p> tags around block elements that shouldn't have them in the first place.

Maybe a formal standardization could be the first step to actually addressing such issues, but it's questionable whether it's worth the bother.