7 ms·
I’ve tried MdBook, Jekyll, and MkDocs. MdBook is slick for basic projects, but I felt it was too minimalistic for me. When I dug into the source for the MdBook
by klodolph 3y ago
I’ve tried MdBook, Jekyll, and MkDocs. MdBook is slick for basic projects, but I felt it was too minimalistic for me. When I dug into the source for the MdBook sites that I liked, I saw that they had extended MdBook with some custom Rust code.
My recommendations are:
- MkDocs: Good default choice, reasonably flexible.
- Jekyll: For people who want a little more flexibility—things like landing pages, blogs, etc.
- Antora: For people who want the best docs, and are willing to put in the most effort. It will manage, for you, the process of generating documentation sites that collect documentation from multiple projects and possibly multiple versions of each project. Asciidoc is full of features you’ll find useful.
Hugo looks like it has a lot of flexibility like Jekyll, but it seems to take more effort to get everything working the way you want, and it also seems like there’s just too much variation in how the different themes work. To be honest, I never really managed to make anything with it—I found out that the theme I was using didn’t have some features I wanted, so I switched to a different theme, but it’s not easy to switch themes. I was too frustrated and gave up.
It looks like MdBook is reasonably active, so I’m sure it will catch up.
- dcchambers 3y agoI am a long time Jekyll user and I still think it's a great tool for blogs, but by far the best SSG for documentation websites I have found is Docusaurus. (https://docusaurus.io/ https://docusaurus.io/) I resisted trying it for the longest time because I didn't want a JavaScript based tool, but I am glad I caved. It's so easy to get started, crazy fast, and the sites are absolutely beautiful out of the box yet easy to customize. The mdx support is awesome too.
- slorber 3y agoDocusaurus maintainer here, happy to read your feedback ;)
- klodolph 3y agoSomehow I missed Docusaurus when I surveyed documentation generators—it looks very good! I can understand the desire to want something not written in JavaScript, and I certainly have my own language prejudices, but when I surveyed static site generators, language choice was all over the map. Like, I was willing to wrangle Ruby installations and gems to get Jekyll working, something I have nearly no experience with.
- KRAKRISMOTT 3y agoAlso https://nextra.site/ https://nextra.site/
- bccdee 3y agoWow, what is up with the material mkdocs theme (https://squidfunk.github.io/mkdocs-material/ https://squidfunk.github.io/mkdocs-material/)? That's an extremely spiffy landing page, especially given that it's for a theme designed for a totally separate piece of software.
- jonasdoesthings 3y agomkdocs-materials is underselling itself as only a theme imo. It bundles a lot of value that mkdocs is missing out of the box as plugins and tweaks, like a good client-side search, page tags, or easy support for a lot of markdown extensions (e.g. code syntax highlighting, admonitions/callouts). From my personal experience mkdocs+mkdocs-material is like GNU+Linux.
- d4rkp4ttern 3y agoAt least for Python documentation, this plus mkdocstrings is great.
- d4rkp4ttern 3y agoCheck out the Pydantic docs pages - they use Mkdocs-material https://docs.pydantic.dev/latest/ https://docs.pydantic.dev/latest/
- Bad_CRC 3y agoI'm a huge user of mkdocs and totally love it. I've trying also bookstack and even it's more "wiki" like it's great too for less tech-savvy people (I usually edit my mkdocs projects in vscode and keet them in git repos and bookstack is all web based).
- ssddanbrown 3y ago> I've trying also bookstack and even it's more "wiki" like it's great too for less tech-savvy people Thanks! My main goal when building BookStack was to build a platform that could be used by all departments, of varying technical confidence, of the company that I was working at since existing open source documentation/wiki systems were positioned for a more technical audience.
- james-bcn 3y agoFor science and statistics, I think Quarto is excellent: https://quarto.org https://quarto.org
- bheadmaster 3y agoI also recommend MkDocs. It was the most painless experience I've had with quickly setting up docs from a bunch of .md files, and the plugins give it enough flexibility for most of the usual stuff I need.
- dsmmcken 3y agoThanks, I hadn't heard of Antora, but the behaviours of assembling docs from multiple repos and using branches for versioning is exactly what I want. Too bad it's not using MDX though, as all our existing docs are markdown + interactive react components.