Skip to content

ADR-0005: Evaluate Documentation Platform with Built-in Access Management (Post-MkDocs)

  • Status: ❌ Rejected
  • Date: 2026-02-09
  • Owners: @cagkan,@enver,@osmank
  • Related: ADR-0002 (Adopt MkDocs + Material)

Why this ADR exists

ADR-0002 adopted MkDocs + Material for internal docs, relying on SSO at the edge/hosting layer (e.g., Cloudflare Access, IAP, oauth2-proxy) rather than implementing authentication inside the doc tool.

A new requirement set now emphasizes built-in access management (role/group based permissions within the platform), in addition to SSO. Static generators like MkDocs can be protected by SSO, but they do not provide native RBAC/page-level permissions.

Goals

  • SSO login via Microsoft Entra ID (Azure AD) (this is sufficient for our needs), ideally with group/role mapping.
  • Built-in access management: roles/groups with section/path/page-level restrictions.
  • Markdown-centric workflow with Markdown import/export portability.
  • Diagrams support: Draw.io (diagrams.net) and Mermaid.
  • Strong navigation UX, advanced search, and good mobile/desktop experience.
  • Keep custom HTML/JS/CSS minimal.

Non-goals

  • Public documentation publishing.
  • Heavy front-end customization.
  • Pure WYSIWYG-only authoring as the primary workflow.

Decision drivers (how we will choose)

We will evaluate candidates using:

  1. Built-in RBAC depth (start with section/path rules, but must support per-page permissions long-term)
  2. Permission inheritance model (folder/namespace inheritance, overrides, explicit denies)
  3. Entra ID integration quality (OIDC/SAML, enforce SSO, and how Entra groups map to app roles)
  4. Editing & auditability (in-app editing is acceptable, but must provide revision history/audit trail)
  5. Markdown portability (source format and import/export quality)
  6. Navigation UX (header/sections/sidebar/ToC)
  7. Search quality (advanced enough for internal use; no large-scale requirements)
  8. Diagrams support (Mermaid and draw.io, or at minimum SVG export/publish)
  9. Operational overhead (single-server deployment acceptable; backups/upgrades should be manageable)
  10. Need for custom code (prefer configuration)

Options considered

Option A — MkDocs + Material (static) + Edge SSO + Multi-site segmentation

  • Strengths: best-in-class docs portal UX, light/dark, Markdown-first, minimal custom front-end, simple ops.
  • Limitations: no built-in RBAC/page permissions; role-based visibility requires multiple sites or edge path policies; search is client-side.
  • Fit: great if coarse-grained access is acceptable; weak if page/section RBAC is mandatory.

Option B — Wiki.js (app + DB) with built-in groups + page rules

  • Strengths: Markdown-centric, built-in groups/permissions and page rules, SSO strategies, search engine modules.
  • Considerations: app+DB operations; clarify Git workflow (wiki↔git sync direction, conflict handling); group-claim→group mapping may need automation.
  • Fit: strong RBAC + Markdown approach, with higher ops cost.

Option C — BookStack (app + DB) with roles/permissions + built-in diagrams.net

  • Strengths: strong built-in roles/permissions; good SSO mapping; draw.io is a major strength.
  • Considerations: Markdown is not always the primary authoring workflow (export/import exists but repo-as-source-of-truth needs validation); Mermaid often requires extra customization.
  • Fit: strong access control + draw.io; evaluate Markdown portability and Mermaid needs.

Current status

We will stay on MkDocs + Material for Appcircle Internal Docs.

Access model:

  • Current internal docs remain Markdown-first and published via MkDocs.
  • Authentication/authorization remains GitHub-based today (GitHub org membership + SSO on hosting layer).
  • If a document requires more granular permissions than GitHub membership can provide, we will share it via Microsoft Office / SharePoint link and rely on SharePoint authorization.

Note

One scenario is not covered by the current model: sharing internal pages with a user who is not a GitHub organization member. There is no active requirement for this scenario today, so it was not evaluated as a blocking decision driver.

Decision rationale (Why we chose this)

  1. We already have a working, Markdown-first workflow and MkDocs is the best fit for PR-based contribution and review.
  2. GitHub SSO / org membership is already operational and aligns with engineering access governance.
  3. Moving to a platform with built-in RBAC would add operational overhead (app + DB), plus workflow ambiguity (Git as source-of-truth vs in-app editing) and migration risk.
  4. For the exceptional cases that need different permissions, SharePoint provides mature authorization without forcing a full platform switch.

Open questions

  • Inheritance rules (details): confirm the exact behavior for section/page permission inheritance, overrides, and explicit denies.
  • Entra ID group mapping (implementation choice): decide whether role/group mapping will be fully claims-based automatic, admin-managed inside the app, or driven by automation/provisioning (and what the operational model will be).
  • Editing model (final choice & mechanics): choose the primary workflow (Git PR-based vs in-app editing) and define how export/sync works, including audit/revision retention requirements.

Next steps (POC plan)

  1. Define POC scope (e.g., ADR + DevOps runbooks).
  2. POC Wiki.js: SSO + 2 roles (Engineering/Security) + page rules + Markdown workflow.
  3. POC BookStack: SSO + role mapping + draw.io page + import/export test.
  4. Run a migration simulation from existing Markdown content.
  5. Score using the decision drivers and document risks/ops costs.
  6. Finalize with an Accepted/Rejected decision (update this ADR or create a follow-up ADR).