Static Documentation Generators

Article

Yuri Marx Perei... · Jan 25, 2021 2m read

Open Exchange

Hi Community,

In the past, technical documentation of the source code and software products was generated in chm, pdf files and documentation generators of the programming languages themselves. This old approach had the following limitations:
1. Outdated documentation;
2. Non-interactive and difficult to consult documentation;
3. Layout unresponsive, unfriendly and not adherent to HTML;
4. Inability to customize the layout of the documentation;
5. Inability to have HTML 5 documentation online and offline.
6. Lack of Markdown support.

Today, there are several documentation generation solutions that produce Web Documentation Portals that are very attractive, interactive, responsive and with static and dynamic options, with full support for HTML 5 and more recently Markdown.

See the table with the most popular open source options:

Documentation Product	Stars
MkDocs Github Repo: https://github.com/mkdocs/mkdocs Static and dynamic documentation generation Simple and lightweight and buit in Python Smart full-text search box Multiple themes and plug-ins Support to Markdown and HTML Integration with Git pages Extensible using Python SPA architecture	11.4k
Docsify Github Repo: https://github.com/docsifyjs/docsify No statically built html files Simple and lightweight (~21kB gzipped) Smart full-text search plugin Multiple themes Useful plugin API Compatible with IE11 Support SSR Support embedded files	16.5k
Docusaurus Github: https://github.com/facebook/docusaurus/ Powered by Markdown Built Using React Ready for Translations Document Versioning Document Search Quick Setup	21.4k
Slate Github: https://github.com/slatedocs/slate Clean, intuitive design Single page documentation Markdown support Out-of-the-box syntax highlighting Write code samples in multiple languages Automatic, smoothly scrolling table of contents Documentation is editable by users via Github RTL Support	31.9k
GitBook https://www.gitbook.com/ Clean, intuitive design Collaborative work/text edition Support to drafts and versioning Single page documentation Markdown support Out-of-the-box syntax highlighting Write code samples in multiple languages Automatic, smoothly scrolling table of contents The better integration with Github Multiple output formats (PDF, HTML5, epub,etc.) Cloud hosting, with free plans to personal projects and paid plans to business use cases	500,000 users

The IRIS Publisher in the Open Exchange allows you extract XData documentation blocks in HTML or Markdown and generate your app documentation website using MkDocs. See the instructions in the article: https://community.intersystems.com/post/creating-documentation-portal-your-intersystems-iris-application.

If you enjoyed, vote in my app: https://openexchange.intersystems.com/contest/current

Ref: https://dev.to/nafis/5-free-static-documentation-generators-you-must-che...