Hello Coders,
This article presents a curated list with modern, open-source documentation generators useful when we want to explain in deep how a software product can be used by others. All tools are free, actively supported, and production-ready.
Thanks for reading! - Content provided by App Generator.
To document a software product is a recommended practice even for small projects and becomes a necessity once the product is getting bigger (more modules, features) or is being used by many users.
Good documentation triggers a faster adoption of your product and might decrease the required LIVE support and 1-1 assistance with your users.
- ✨ MkDocs - Python based
- ✨ Docsify - Vue based
- ✨ Docute - Vue based
- ✨ Vuepress - Vue based
- ✨ Docusaurus - powered by React
Regarding the list, I've used Mkdocs in production but I'm super tempted to switch to Docsify that looks damn good, is actively supported, and provides search and internationalization "out of the box".
Regarding this type of products, I noticed a few common problems:
Search - this is a big problem and Lunr solves it when your docs are still light. Algolia comes to the rescue but is not free.
Internationalization (i18n) - A modern documentation system, IMO, should provide this feature. This is my first reason not to use MkDocs for my future projects.
Technology lockdown - It would be nice to start using a documentation system without being forced to learn the technology that powers the product. Docusaurus might be a good choice but requires a minimum React knowledge and this can be a show stopper for a backend developer or someone that dislikes React.
Feel free to suggest more generators or submit PROS, CONS remarks in the comments section. Thank You!
✨ MkDocs
Simple, Python-based documentation generator that uses Markdown format for input files - BSD-2-Clause License.
Official information - 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.
Github metrics
- 11k Stars, 1.6k Forks, Last commit: 5days ago
- 120 open issues and 17 pulls requests
- Used by 9k users, 160 Contributors
PROS (advantages of using MkDocs)
- Easy to set up, well documented
- Fast in development and also in production
- Default Search feature by Lunr, Algolia can be integrated with ease
- Components via Markdown-Include
CONS (disadvantages)
- No Multilanguage support
- Hardcoded footer - can be hacked but unsupported by default
- Few themes available
✨ Docsify
A modern Vue-based documentation generator that renders the files without a translation phase. In other words, the docs are rendered as a classic SPA.
Official Information - A magical documentation site generator. Docsify generates your documentation website on the fly. Unlike GitBook, it does not generate static HTML files. Instead, it smartly loads and parses your Markdown files and displays them as a website. To start using it, all you need to do is create an index.html.
Github metrics
- 16k Stars, 4k Forks, Latest commit 20h ago (not so relevant maybe)
- 113 open issues and 33 pulls requests
- Used by 1.6k users, 154 contributors
PROS
- No statically built HTML files
- Simple and lightweight
- Smart full-text search plugin
- Multiple themes
- SSR support
- Internationalization
CONS
- The users should be familiar with Vue, Nodejs, and related tools
✨ Docute
Docute is basically a JavaScript file that fetches Markdown files and renders them as a single-page application.
It's totally runtime-driven so there's no server-side components involved which also means there's no build process. You only need to create an HTML file and a bunch of Markdown documents and your website is almost ready!
Docsify and Docute are pretty much the same, but with different UI and different usages.
Docute (60kB) is 3 times bigger than Docisfy (20kB), because we use Vue, Vue Router and Vuex while Docsify uses vanilla JavaScript under the hood.
Github metrics
- 3k Stars, 400 Forks, Last commit: 6mo ago
- 71 open issues and 11 pulls requests
- Used by 24 users, 16 contributors
✨ Vuepress
Vue-powered Static Site Generator with a minimal setup with markdown-centered project structure.
VuePress generates pre-rendered static HTML for each page and runs as a SPA once a page is loaded.
Github metrics
- 18k Stars, 3.6k Forks, Latest commit 20h ago (not so relevant maybe)
- 300+ open issues and 100 pulls requests
- Used by 13k users, 350 contributors
PROS
- No statically built HTML files
- Simple and lightweight
- Internationalization
- Vue can be used in Markdown files
✨ Docusaurus
This generator is built using React to build the UI and Markdown/MDX as input format.
Github metrics
- 20k Stars, 2.4k Forks, Last commit: 18h ago (not so relevant maybe)
- 160 open issues and 18 pulls requests
- Used by 6k users, 500 contributors
PROS
- Fast in production - has an internal architecture similar to Gatsby (PRPL pattern)
- Use React and MDX
Thanks again! Let me know your thoughts in the comments.
Btw, my (nick) name is Sm0ke and I'm pretty active also on Twitter.
Top comments (11)
Both front and back ends of docsify are suitable for use, no nodejs or any other runtime/compilation tools are needed, only html + markdown
Thank you for your feedback.
Regarding the search, can you provide more information?
I wonder how the default search feature manages a large index (1k pages or more).
Currently I have not used docsify to build a large online document (the company has its own wiki system), but the largest online document I have built using it is zhuyanxue.liuli.moe/#/, which contains 404 files , 32878 words, no major problems have been encountered in the search
Noted.
I will try hexo/hugo - Ty!
The Lighthouse score for Docsify looks a little bit lower than MkDocs (just run it on your deployment).
Any tweaks to improve the score?
Performance is difficult to become a decisive factor in most application scenarios, especially in this era when hardware is worthless. . .
I'm ok with accessing and consume good documentation rendered by a SPA but Google is the bad guy in this equation.
Anyway, .. this is not a show stopper, for me at least, to use Docsify.
Thanks again for your time!
Thanks!
Docsify deserves a closer look.
Nice list! Ty!
Don't see anything related to search. There is a native plugin available?
Ty!
Noted, Ty!