The wikis are now using the new authentication system.
If you did not migrate your account yet, visit https://idp-portal-info.suse.com/

Opensuse-docs/prep-meeting-11-20

Jump to: navigation, search

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

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