Research API documentation website generator

[zehnm]

As an integration developer I'd like to have an easy to access and browsable API documentation. As an API developer I'd like to have a simple documentation tool, preferrably in Markdown, with diagram embedding support and not have to learn yet another documentation format or deal with html & css layouting.

The current solution with simple markdown files in this GitHub repository is not very end-user friendly. It's very simple for API developers to add things, but it's getting more complicated to group content and adding an easy navigation.

Research better documentation website generators and evaluate which tool to use. Requirements:

• easy to use for writing technical documentation, tailored to developers
• must support Markdown files as input
• GitHub integration, automated publishing with changed or added input documents
• should support Mermaid diagrams
  • already used in markdown files
  • supported by GitHub: https://github.blog/2022-02-14-include-diagrams-markdown-files-mermaid/
• should support draw.io diagrams
• free to use or with reasonable licensing costs

At the moment we are aware of the following solutions:

• Hugo
  • Used in the former YIO project
• GitBook
  • Free for open source projects

Reddit discussion with lots of options: https://www.reddit.com/r/selfhosted/comments/kphfbl/is_there_a_self_hosted_gitbook_alternative/