The various documentation platforms can be broadly categorized into two main types based on their architecture and workflow:
These tools generate a website from plain-text files stored in your GitHub repository. The documentation lives alongside your code, and the entire software development workflow (pull requests, versioning, code reviews) is used for the documentation as well.
| Tool | Description |
|---|---|
| Github Pages (This Site) | Jekyll one of the original static site generators, powered by Ruby. It is the engine behind GitHub Pages, making it a seamless option for hosting your documentation directly from your GitHub repo for free. |
| MkDocs | A fast and simple static site generator written in Python, geared towards technical documentation. It uses Markdown source files and has a variety of themes and plugins available. |
| Docusaurus | An open-source static site generator built on React that is popular for documentation sites. It is easy to use and provides a modern look and feel with built-in search and versioning features. |
| Quarto | An open-source scientific and technical publishing system that allows you to create dynamic content using Markdown and integrate executable code (Python, R, Julia, etc.) into your documentation. |
| DocFX | A static site generator for building and publishing API documentation for .NET projects, but can also be used for general Markdown documentation. It’s developed by Microsoft and is highly customizable. |
N.B. Unable to generate working examples for MkDocs due to installation restrictions.
If you prefer a hosted solution with a more traditional editing interface but still want your source content in GitHub, some SaaS products offer synchronization.
| Tool | Description |
|---|---|
| GitBook | A modern platform for creating and managing documentation. It can connect to your GitHub repository and automatically sync content, providing a polished user interface while keeping the source in Git. |
| Document360 | A knowledge base platform that offers GitHub integration for one-way sync of Markdown files from a GitHub repository into Document360. The synced articles are read-only within Document360’s editor; any changes must be made in the source GitHub repository and then synced back. |
| Notion or Confluence (with integration) | While their primary storage isn’t Git, they can be integrated or used in conjunction with a docs-as-code approach to serve different audiences, with the source of truth remaining in the GitHub repo. |
N.B. Unable to view complted GitBook as Gitbook.io is restricred by ISO, due to phising issues.
The “docs-as-code” approach using a static site generator and plain text files is generally considered best practice for software architecture documentation because it aligns with engineering workflows and facilitates version control and collaboration within the existing toolset.
Architecture documentation often requires diagrams. These tools allow you to define diagrams using text-based syntax, which can be versioned in Git like the rest of your documentation.
| Tool | Description |
|---|---|
| Mermaid | A JavaScript-based diagramming and charting tool that uses a simple markdown-like syntax to define diagrams. It is widely supported in various documentation platforms, including GitHub, Docusaurus, and MkDocs. |
| PlantUML | These tools render simple text-based descriptions into diagrams (UML, C4 model, flowcharts, etc.). GitHub natively supports rendering Mermaid diagrams inline within Markdown files, which is a significant advantage. |
| Structurizr | This tool is based on the C4 model for visualizing software architecture. It allows you to create diagrams and documentation from a single model using code or a Domain Specific Language (DSL), perfect for technical people who want to manage architecture rigorously in source control. |
| Draw.io (now diagrams.net) | While it has a traditional UI editor, it also offers a C4 model plugin and can store diagram definitions in a version-control-friendly format (like XML or text) within your GitHub repo. |
| Documentation Tool | Mermaid | Plantuml | Structurizr |
|---|---|---|---|
| Docusaurus | Yes (via plugins) | Yes (via plugins) | Yes (via plugins) |
| MkDocs | Yes (via plugins) | Yes (via plugins) | Yes (via plugins) |
| Quarto | Yes (native support) | Yes (via plugins) | No (requires pre-generation) |
| DocFx | Yes (native support) | Yes (via plugins) | No (requires pre-generation) |
| GitHub Pages | Yes (native support) | No (requires pre-generation) | No (requires pre-generation) |
Representing PlantUML and Structurizr diagrams in the recommended applications is generally achieved using plugins, extensions, or by generating images as part of your build pipeline. Since these tools use static site generation, the diagrams are typically converted to SVG or PNG images at build time rather than rendered dynamically in the browser.
The best options that meet all requirements, especially the GitHub-backed document repository, are the open-source static site generators such as Docusaurus, MkDocs, Quarto, and GitHub Pages. These platforms fully support the “docs-as-code” workflow required by a GitHub-backed repository. Here is a breakdown of why these are the top choices and how they meet your needs:
| Requirement | Explanation |
|---|---|
| GitHub-backed document repository | All these tools use plain Markdown files stored in your GitHub repo as the source of truth. |
| 20 active contributing users | The contribution model leverages standard Git workflows (pull requests, branching, code reviews), which scales well for active engineering teams. |
| 1000+ readonly users | Static site generators produce highly performant, scalable websites that can handle thousands of concurrent read-only users without performance issues. |
| Support for Markdown | Markdown is the native authoring format for all of them. |
| Support for PlantUML, Mermaid, Structurizr | Mermaid is natively supported by GitHub and many of these generators. PlantUML and Structurizr are also widely supported through extensions, plugins, or pre-processing during the build pipeline. |
| Platform | Notes |
|---|---|
| Docusaurus | Excellent balance of modern design, ease of use, built-in features (search, versioning), and a React-based structure for customization. |
| MkDocs | Simple, fast, and highly effective for technical documentation, using Python. Easy to configure plugins for diagram support. |
| Quarto | Ideal for technical and scientific documentation, integrating executable code and advanced formatting capabilities. |
| GitHub Pages (This Site) | The underlying hosting platform for the others (often used with Jekyll or MkDocs), offering a seamless, free hosting solution directly from your repo. |
| Platform | Notes |
|---|---|
| Azure DevOps Wiki | Its primary storage is not a GitHub repo (it uses an Azure repo for “code wiki”), and native support for all diagram types (especially PlantUML and Structurizr) is limited without workarounds. |
| Confluence & Notion | These are traditional CMS/wiki platforms where the primary storage is their own database, not your GitHub repo. While integrations exist, they often rely on one-way syncs or embedding, which doesn’t fully align with the “GitHub-backed” requirement. |
| Document360 & GitBook | These are SaaS products. GitBook started with open-source roots but now operates as a hosted solution with sync capabilities. Document360 offers a one-way sync from GitHub, but the source of truth within the app is its own database. |
| Read The Docs | Excellent for hosting documentation, particularly Sphinx projects, but often used for existing projects rather than a standalone platform choice like Docusaurus or MkDocs for greenfield projects. It still fits the requirements as a hosting solution for content from a GitHub repo. |
The best fit version applications use the following versions of Markdown.
In summary, all four options are either based on the highly compatible CommonMark or GFM specifications, ensuring that your documentation is largely portable and readable across different platforms.
graph TD
%% Early Influences
A[Plain Text Email / Usenet] --> D
B[Setext 1992] --> D
C[reStructuredText 2002] --> D
%% The Progenitor
D{Markdown v1.0.1 2004<br/>John Gruber & Aaron Swartz}
%% Early Branching
D --> E[MultiMarkdown 2005]
D --> F[PHP Markdown Extra]
%% Major Modern Flavors
D --> G[GitHub Flavored Markdown GFM]
D --> H[Stack Overflow Markdown]
%% Standardization Efforts
G --> I((CommonMark 2014))
H --> I
%% Specialized Descendants
I --> J[R Markdown / Quarto]
I --> K[Obsidian / PKMS Flavors]
E --> L[Pandoc's Markdown]
%% Modern Integrations
K --> M[Mermaid / Diagrams]
J --> N[Academic Publishing]
@startuml
skinparam handwritten true
actor User
rectangle "Documentation System" {
User --> (Create Docs)
User --> (Edit Docs)
User --> (View Docs)
(Create Docs) --> (Store in GitHub)
(Edit Docs) --> (Store in GitHub)
(View Docs) --> (Render from GitHub)
}
@enduml
workspace {
model {
user = person "User" {
description "A user of the documentation system."
}
documentationSystem = softwareSystem "Documentation System" {
description "A system for creating, editing, and viewing documentation."
createDocs = container "Create Docs" {
description "Allows users to create new documentation."
}
editDocs = container "Edit Docs" {
description "Allows users to edit existing documentation."
}
viewDocs = container "View Docs" {
description "Allows users to view documentation."
}
storeInGitHub = container "Store in GitHub" {
description "Stores documentation in a GitHub repository."
}
renderFromGitHub = container "Render from GitHub" {
description "Renders documentation from the GitHub repository."
}
}
user -> createDocs "Creates documentation"
user -> editDocs "Edits documentation"
user -> viewDocs "Views documentation"
createDocs -> storeInGitHub "Stores in"
editDocs -> storeInGitHub "Stores in"
viewDocs -> renderFromGitHub "Renders from"
}
views {
systemContext documentationSystem {
include *
autolayout lr
}
container documentationSystem {
include *
autolayout lr
}
}
}