Your Web News in One Place

Help Webnuz

Referal links:

Sign up for GreenGeeks web hosting
December 13, 2020 11:24 am GMT

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

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.


Original Link: https://dev.to/sm0ke/documentation-generators-a-curated-list-mkdocs-docsify-vuepress-2794

Share this article:    Share on Facebook
View Full Article

Dev To

An online community for sharing and discovering great ideas, having debates, and making friends

More About this Source Visit Dev To