4 ms·
The footer at that page says the site uses MkDocs [1]. Has anyone used it and knows how it compares to Sphinx and MyST-Parsee [2]? [1]: https://www.mkdocs.org/
by kinow 4y ago
The footer at that page says the site uses MkDocs [1]. Has anyone used it and knows how it compares to Sphinx and MyST-Parsee [2]?
[1]: https://www.mkdocs.org/ https://www.mkdocs.org/
[2]: https://www.sphinx-doc.org/en/master/usage/markdown.html https://www.sphinx-doc.org/en/master/usage/markdown.html
- asicsp 4y agoI'm not familiar with Sphinx/MyST. Textual (https://textual.textualize.io/ https://textual.textualize.io/) uses MkDocs - I especially like the search feature.
- kinow 4y agoI am using Sphinx with MyST as I had seen it being used in the JupyterHub. I have textual on my bookmarks (have a future task to write a TUI for an app and need to choose between urwid and textual/rich [for HPC - ie older OS, lots of security measures around the terminal and access]). I did a quick search but looks like I cannot use Sphinx directives with MkDocs [1]. I will search some more after coffee break, but there are directives I am using in other Sphinx (reSt and myst-md) that I would prefer to keep using if possible (I've also modified and monkey-patched some directives and loaded locally with sphinx/py). Thanks [1]: https://github.com/mkdocs/mkdocs/discussions/2390 https://github.com/mkdocs/mkdocs/discussions/2390
- chakspak 4y agoSphinx is powerful and hard to beat if you're looking to generate documentation from code in multiple languages or export to multiple document formats, but it's slow and creaky and hard to hack on. MkDocs by itself is okay, but Material for MkDocs is life-changing: https://squidfunk.github.io/mkdocs-material/ https://squidfunk.github.io/mkdocs-material/ If it does everything you need it to do, it'll make creating and editing sites much faster and with fewer opportunities to break things.
- c0balt 4y agoMkdocs has quite a good ecosysten especially around Mkdocs Material[0] used by projects like FastApi[1]. Mkdocs is quite easy to setup and has features comparable to Sphinx and MyST-Parse. Iirc it has less stuff out of the box compared to Sphinx but nakes up for it with a mature plugin ecosystem. [0]: https://squidfunk.github.io/mkdocs-material/ https://squidfunk.github.io/mkdocs-material/ [1]: https://fastapi.tiangolo.com/ https://fastapi.tiangolo.com/
- kinow 4y agoThanks for the brief comparison and for the links!
- freetonik 4y agoI've used both MkDocs and Sphinx, and had better experience with the former. Sphinx is more powerful, I guess, but for my purposes MkDocs was enough, and it is much simpler to set up right. The Material theme [1] is very nice, looks good and search works out of the box. Thanks for reminding me about this, I haven't looked at Material theme for a while, and it seems like they have some nice new features like code annotations [2]. Back when I was using this theme for some educational materials this feature would've been very useful to me. [1]: https://squidfunk.github.io/mkdocs-material/ https://squidfunk.github.io/mkdocs-material/ [2]: https://squidfunk.github.io/mkdocs-material/reference/code-blocks/#code-annotations https://squidfunk.github.io/mkdocs-material/reference/code-b...