DEV Community

loading...
Cover image for Documentation Generators - A curated list: MkDocs, Docsify, Vuepress

Documentation Generators - A curated list: MkDocs, Docsify, Vuepress

sm0ke profile image Sm0ke Originally published at blog.appseed.us ・4 min read

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! This content is provided by AppSeed, a platform used by many developers across the globe.


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.

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

Documentation Generator MkDocs - Homepage screen


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

Documentation Generator Docsify - Homepage screen


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

Documentation Generator Docute - Homepage screen


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

Documentation Generator Vuepress - Homepage screen


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

Documentation Generator Vuepress - Homepage screen


Thanks again! Let me know your thoughts in the comments.


Btw, my (nick) name is Sm0ke and I'm pretty active also on Twitter.

Discussion (11)

pic
Editor guide
Collapse
rxliuli profile image
rxliuli

Both front and back ends of docsify are suitable for use, no nodejs or any other runtime/compilation tools are needed, only html + markdown

Collapse
sm0ke profile image
Sm0ke Author

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).

Collapse
rxliuli profile image
rxliuli

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

In addition, you don’t seem to mention hexo/hugo. As far as I know, the official website of vue.js is built using hexo

Thread Thread
sm0ke profile image
Sm0ke Author

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?

Thread Thread
rxliuli profile image
rxliuli

Performance is difficult to become a decisive factor in most application scenarios, especially in this era when hardware is worthless. . .

Thread Thread
sm0ke profile image
Sm0ke Author

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!

Collapse
uithemes profile image
ui-themes

Thanks!
Docsify deserves a closer look.

Collapse
crearesite profile image
WebsiteMarket

Nice list! Ty!

Collapse
Sloan, the sloth mascot
Comment deleted
Collapse
sm0ke profile image
Sm0ke Author

Don't see anything related to search. There is a native plugin available?
Ty!

Collapse
sm0ke profile image
Sm0ke Author

Noted, Ty!