Opensuse-docs/prep-meeting-11-20

Desired features

1. GitHub integration
2. full-text search
3. host agnostic / low footprint
4. FOSS

Most promising

Sphinx (as a service with "Read the Docs")

• restructured text, markdown on Python stack
• many themes as per https://sphinx-themes.org/
• good reputation
• not hot reload

MkDocs

• markdown on Python stack
• hot reload
• quite neutral on what env it needs
• super simple to use
• supports all flavours of markdown via python Markdown library
• active community / easy support

BookStack

• WSIWYG, Markdown on Laravel, PHP, MySQL tech stack
• super clean
• user-friendly front-end
• configuration aside, has a very flat learning curve

Antora + Adoc

• AsciiDoc, JS-equivalent of MkDocs (Node driver for Ascidoctor)
• the AsciiDoc part of the tech stack is arguably better than any rival as far as formatting & typography
• the Antora part of the tech stack is relatively young / less battle proven
• the AsciiDoc has quite a learning curve

The come-afters

Hugo & Docsy

• pure Go web framework
• nice blend of markdown and html-like syntaxt via shortcodes
• perhaps an overkill if we don't need to build a full website
• some learning curve to expect, especially if using markdown with "shortcodes"

Docusaurus

• markdown, Node stack fronted with ReactJS
• hot reload
• tight github integration
• godawful docs
• overkill if we don't use ReactJS
• some learning curve to expect

en.opensuse.org

• in house
• kinda not so beautiful

Gatsby

• for JS-heavy websites
• too heavy of a tech debt for future maintainers

VuePress

• same as for Gatsby

Dauxio

• mostly for API

mdBook

• lacks features

Doxgen

• mostly for APIs

GitHub Pages

• locked into Github.com
• generic web page generator not particularily oriented toward documentation

Gitbook.com

• non FOSS
• non platform agnostic