Documentation Conventions

How to write and structure Kredal documentation so it renders in Fumadocs and passes CI.

File format

Markdown, MDX-compatible. Plain markdown renders in Fumadocs. Avoid raw HTML unless necessary; if used, it must be valid JSX (self-close <br />, className not class).

Frontmatter is required. Every page starts with title and description:

---
title: Short Page Title
description: One sentence describing what this page covers.
---

One # H1 per file, immediately after the frontmatter, matching the title.
Relative links between docs (../reference/scoring-engine.md), so they work on GitHub and in the built site.

Structure (Diátaxis)

Put each page in the right mode:

tutorials/ — a lesson that takes a beginner from nothing to a working result.
how-to/ — numbered steps to accomplish one real task. No conceptual detours.
reference/ — dry, complete, accurate. Tables over prose.
explanation/ — the "why". Discussion, trade-offs, background.
adr/ — one decision per file, MADR format.

Diagrams

Use Mermaid fenced code blocks (```mermaid). Fumadocs renders them. Prefer diagrams-as-code over images so they stay in version control and are searchable.

reference/database-schema.md and reference/scoring-engine.md are generated from code by npm run docs:gen. They carry a banner and must not be hand-edited — change the source (kredal-app/supabase/migrations/*.sql, kredal-app/src/lib/scoring/rules.ts) and regenerate. CI fails if they drift.

Language & compliance rules (enforced by CI/Vale)

Kredal handles a regulated domain. Public-facing copy must:

Use "readiness assessment", "risk flags", "recommended fixes", "application pack".
Never claim or imply "guaranteed approval", "get approved", or that Kredal is a bank, lender, auditor, or tax advisor.
Never present the score as a credit score sold to banks.
Cite the $250B GCC SME financing gap as the market anchor — not the unverified $475B MENA-wide figure. Do not cite "BookBI" or "Metric" as competitors (unverified in research).

Changelog

We use Conventional Commits. Notable changes are summarised in the repository CHANGELOG.md. There is no package to version — this is an application, not a published library.