On: MkDocs 1.0

[lima]

How do mkdocs and asciidoctor compare to reStructuredRext/Sphinx nowadays?

[brianjking → lima]

I'm not familiar with asciidoctor, however, I have a fair amount of experience with Sphinx & MkDocs.

POSITIVES OF MkDocs over Sphinx

* Markdown seems to be easier for people to understand and are familiar with as opposed to reStructuredText. However, Sphinx now does allow you to use Markdown as well as reStructuredText.

* MkDocs seems to have more themes that are actively developed. My favorite is mkdocs-material (https://github.com/squidfunk/mkdocs-material), example can be seen here: https://squidfunk.github.io/mkdocs-material/.

* Most of the features of Sphinx can be used natively or with some plugins for MkDocs. (https://github.com/brianjking/1upkeyboard-docs/blob/master/m...)

* Easy to implement MkDocs with Travis-CI or other CI systems to test/build/deploy documentation on GitHub pages, Gitlab pages, etc. (https://github.com/brianjking/1upkeyboard-docs/blob/master/....)

The times I feel Sphinx is definitely a better choice than MkDocs (from my personal experience):

* If you want to generate PDF & ePUB copies of your files Sphinx seems much more direct, especially if you can use ReadTheDocs (https://readthedocs.org/). Although, there are several MkDocs methods of generating your docs as a PDF using pandoc or other systems. However, depending on what plugins you have in your mkdocs it may cause problems. (https://github.com/search?q=mkdocs+pdf, https://github.com/search?q=mkdocs+pandoc).

* Sphinx seems better for auto documentation for APIs and other code documentation.

[sashk → brianjking]

sphinx allows to test code snippets in the documentation. is this available in mkdocs?

[type0 → lima]

They're are quite different beasts all together. I can't think of any reason to use reST and Sphinx under any circumstance other than Python projects. Asciidoctor.js actually has a site generator these days called Antora (aimed at building docs from multiple git repos) it is still far from complete on features compared to Sphinx. MkDocs looks good for small projects although I probably would just use mdBook if there's a need to write in Markdown for some reason.

[mixmastamyk → lima]

Also wondering about extensions, how are those handled? Or is this for plain documents only? For example in Sphinx you can mark up figures, youtube videos, graphviz graphs, etc. Are those plugins available with mkdocs?

What about a book with parts? That's one area that Sphinx falls down, and they've been dragging their feet on it so far.

[therealmarv → mixmastamyk]

There are plenty of mkdocs plugins for advanced documentation features.