You love diagrams but don't want to spend time positioning elements.

Your diagram keeps evolving, you want the layout to re-adjust automatically.

You prefer to describe your diagrams with an intuitive text description.

On Markdown: I don't like it for self publishing and I tried using it for my resume and decidedly didn't like the formatting. I think it excels for simple note taking and documentation but for making books it sucks. So I ended up using HTML but for the books I am still like DocBook or perhaps TeX or derivative but it is a learning curve. I now truly believe in write -once and format - many

MkDocs is a fast, simple and downright gorgeous static site generator that's geared towards building project documentation. Documentation source files are written in Markdown, and configured with a single YAML configuration file.