Writing Guide

This page demonstrates the features available for writing Keymate documentation. Use it as a reference when creating new pages.

SEO Best Practices

Every documentation page must include proper frontmatter for search engine discoverability:

---
title: Your Page Title # Appears in browser tab and search results
description: A concise summary # Used by search engines (max ~160 chars)
sidebar_position: 1 # Controls ordering in the sidebar
keywords: [keyword1, keyword2] # Helps search engine indexing
tags: [tag1, tag2] # Used for tag-based navigation
---

SEO Checklist

title: Keep it concise and descriptive (50-60 chars ideal).
description: Write a unique summary for every page. This is what appears in Google search results.
keywords: Add 3-5 relevant terms.
Use headings (##, ###) to structure content — search engines use these for indexing.
Use descriptive link text instead of "click here".

Before you write

Read the Writing Style & Standards for voice, tone, terminology, and formatting rules. For contribution workflow and review process, see Contributing.

Code Blocks

Basic Syntax Highlighting

Use fenced code blocks with the language identifier:

```java
public class Example {
    // your code here
}
```

Renders as:

public class PolicyEvaluator {

    private final PolicyEngine engine;

    public EvaluationResult evaluate(AccessRequest request) {
        Policy policy = engine.resolve(request.getResource());
        return policy.evaluate(request.getSubject(), request.getContext());
    }
}

Supported Languages

java, typescript, javascript, json, yaml, bash, groovy, toml, python, sql, go, and more.

Title and Line Highlighting

```typescript title="src/middleware/auth.ts" {3-5}
import { KeymateClient } from "@keymate/sdk";

const client = new KeymateClient({
  endpoint: "https://keymate.io/api",
  apiKey: process.env.KEYMATE_API_KEY,
});
```

Renders as:

src/middleware/auth.ts
import { KeymateClient } from "@keymate/sdk";

const client = new KeymateClient({
  endpoint: "https://keymate.io/api",
  apiKey: process.env.KEYMATE_API_KEY,
});

Multi-language Tabs

import Tabs from '@theme/Tabs';
import TabItem from '@theme/TabItem';

<Tabs>
<TabItem value="java" label="Java">

```java
KeymateClient client = KeymateClient.builder()
    .endpoint("https://keymate.io/api")
    .build();
```

</TabItem>
<TabItem value="ts" label="TypeScript">

```typescript
const client = new KeymateClient({
  endpoint: "https://keymate.io/api",
});
```

</TabItem>
</Tabs>

Java
TypeScript

KeymateClient client = KeymateClient.builder()
    .endpoint("https://keymate.io/api")
    .build();

const client = new KeymateClient({
  endpoint: "https://keymate.io/api",
});

Mermaid Diagrams

Write diagrams as code using Mermaid syntax. They render automatically.

Sequence Diagram

```mermaid
sequenceDiagram
    participant Client
    participant Gateway
    participant Keymate
    participant FGA Engine

    Client->>Gateway: API Request
    Gateway->>Keymate: Evaluate Access
    Keymate->>FGA Engine: Check Relationship
    FGA Engine-->>Keymate: Allowed
    Keymate-->>Gateway: Decision: PERMIT
    Gateway-->>Client: 200 OK
```

Flowchart

Architecture Diagram

Images

All image components are globally available — no import needed. Click on any image to zoom in (image zoom is enabled site-wide).

Image Standards

File Format

Use Case	Format	Notes
Screenshots, photos	PNG (source)	image processing service converts to AVIF automatically via `f:avif`
Logos, icons, UI shapes	SVG	Vector, scales to any resolution
Diagrams	Mermaid or SVG	Prefer Mermaid for maintainability

Store source images as high-quality PNG. Never commit lossy-compressed screenshots (JPEG artifacts are permanent).

Resolution and Size

Capture all screenshots at 2x resolution (Retina/HiDPI). A screenshot displayed at 800px must be captured at 1600px.
Standard display widths: 800px (default), 1200px (wide/detailed views).
Target file size: under 100 KB per image (25-50 KB preferred). Use TinyPNG or Squoosh to compress before committing.
Use a consistent 16:9 aspect ratio for full-screen captures.

File Naming

Use lowercase, hyphen-separated, descriptive names:

Good:  org-creation-form.png
       policy-editor-dark-mode.png
       rbac-vs-abac-comparison.png

Bad:   screenshot1.png
       IMG_2847.png
       Screen Shot 2026-03-12.png

File Location

Place images next to the Markdown file that uses them (co-located). This gives you Webpack content hashing for cache busting and keeps related content together.

docs/
  getting-started/
    img/
      admin-console-overview.png
      first-policy-created.png
    quickstart.md          ← references ./img/admin-console-overview.png

Reserve /static/img/ only for global assets (favicon, logo, social preview).

Screenshot Capture Rules

Use Incognito/Private mode to avoid browser extensions and personal bookmarks.
No browser chrome: hide the address bar, bookmarks bar, and tabs. Use Chrome DevTools (Cmd+Shift+P > "Capture screenshot") or CleanShot X.
Use realistic data in screenshots. Never use lorem ipsum or placeholder names like "Test User".
Keep only the relevant UI area visible. Crop out empty space and unrelated panels.

Alt Text

Every image must have descriptive alt text. This is used by screen readers, search engines, and LLMs.

Good:  alt="Keymate Admin Console showing the organization creation form with name and domain fields"
       alt="Policy evaluation flow from access request to permit or deny decision"

Bad:   alt="Screenshot"
       alt="Image 1"
       alt=""  (only for purely decorative images)

Rules:

Do not start with "Image of..." or "Screenshot of..." (screen readers already announce it as an image).
Describe the purpose, not just the appearance.
Keep it under 140 characters.

Annotations

When annotating screenshots to highlight UI elements:

Element	Style
Highlight boxes and arrows	Keymate Blue `#3391F8`, 2-3px border, rounded corners
Focus effect	70% opacity black overlay on the rest of the image
Text labels on images	Inter font, minimum 14px
Line style	Solid lines, not hand-drawn

Recommended tools: CleanShot X (Mac), Snagit (cross-platform), Figma (team annotation kits).

CDN Image (Blob Storage)

Images stored in Azure Blob Storage are automatically served through image processing service (AVIF conversion + resize) and cached by Front Door. Use a short blob path starting with /docs/:

<Image
  src="/docs/keymate_long_logo.png"
  alt="Keymate logo served from CDN as AVIF"
  caption="Blob storage image — auto-converted to AVIF, resized, and cached by Front Door."
/>

Blob storage image — auto-converted to AVIF, resized, and cached by Front Door.

CDN Image with Custom Width

When width is a number, it controls both the CSS max-width and the image processing service resize width:

<Image
  src="/docs/keymate_long_logo.png"
  alt="Keymate logo at 400px"
  width={400}
/>

External Image (No CDN)

Images from external URLs or local paths are used as-is — no image processing service processing:

<Image src="https://picsum.photos/id/237/600/400" alt="Sample external image" />

Local Image (No CDN)

Images from /img/ (the static/img/ directory) bypass image processing service:

<Image src="/img/keymate-logo.png" alt="Keymate logo from static directory" width={400} />

Image with Caption

<Image
  src="https://picsum.photos/id/42/600/300"
  alt="Landscape with mountains"
  caption="Figure 1: Use the caption prop to describe what the image shows."
/>

Landscape with mountains — Figure 1: Use the caption prop to describe what the image shows.

Image Grid

Use <ImageGrid> to show multiple images side by side:

<ImageGrid cols={3}>
  <Image src="https://picsum.photos/id/10/300/200" alt="Forest" />
  <Image src="https://picsum.photos/id/17/300/200" alt="Mountains" />
  <Image src="https://picsum.photos/id/29/300/200" alt="Coast" />
</ImageGrid>

Video

Embed YouTube or Vimeo videos with a single line. Just paste the video URL:

<Video
  url="https://www.youtube.com/watch?v=dQw4w9WgXcQ"
  title="Example video"
/>

Cards

Use cards to create navigation blocks or highlight features.

Single Card

<Card
  title="Getting Started"
  description="Set up Keymate in your environment."
  to="/getting-started"
/>

Card Grid

<CardGrid cols={3}>
  <Card
    title="Authorization"
    icon="🔐"
    description="Fine-grained access control and policy engine."
    to="/concepts/authorization"
  />
  <Card
    title="Architecture"
    icon="🏗️"
    description="System design and deployment topology."
    to="/architecture"
  />
  <Card
    title="Integrations"
    icon="🔌"
    description="Connect with gateways, identity providers, and more."
    to="/integrations"
  />
</CardGrid>

🔐Authorization

Fine-grained access control and policy engine.

🏗️Architecture

System design and deployment topology.

🔌Integrations

Connect with gateways, identity providers, and more.

Admonitions

Use admonitions to highlight important information:

:::note
General information the reader should know.
:::

:::tip
Helpful advice or best practices.
:::

:::info
Additional context or background information.
:::

:::warning
Something the reader should be careful about.
:::

:::danger
Critical information — risk of data loss or security issues.
:::

Renders as:

note

General information the reader should know.

tip

Helpful advice or best practices.

info

Additional context or background information.

warning

Something the reader should be careful about.

danger

Critical information — risk of data loss or security issues.

Tables

| Feature            | RBAC | ABAC | ReBAC   |
| ------------------ | ---- | ---- | ------- |
| Role-based         | Yes  | No   | No      |
| Attribute-based    | No   | Yes  | Partial |
| Relationship-based | No   | No   | Yes     |

Feature	RBAC	ABAC	ReBAC
Role-based	Yes	No	No
Attribute-based	No	Yes	Partial
Relationship-based	No	No	Yes

Links

Internal Links

Link to other docs using relative paths:

See the [Architecture overview](../architecture/index.md) for details.

External Links

Visit the [FGA engine documentation](https://fga-backends.dev/docs) for more information.

Details / Collapsible Sections

<details>
<summary>Click to expand: Full configuration example</summary>

Content goes here. You can include code blocks, lists, etc.

</details>

Click to expand: Full configuration example

keymate:
  policy-engine:
    evaluation-mode: strict
    cache-ttl: 300s
  access-gateway:
    upstream: http://backend:8080
    enforce: true

Page Templates

When creating a new documentation page, start from one of the ready-made templates in the _templates/ directory:

Template	Use For
`top-level-landing.md`	Top-level section entry pages
`section-landing.md`	Sub-section entry pages
`concept-page.md`	Concept explanations, feature descriptions
`guide-page.md`	Step-by-step guides, walkthroughs
`reference-page.md`	API docs, configuration reference, specifications
`troubleshooting-page.md`	Problem diagnosis and resolution guides
`test-scenario.md`	High-level test scenarios for QA and demos

FAQ

Use the <FAQ> and <FAQItem> components to create FAQ sections with automatic JSON-LD structured data for SEO.

<FAQ>
  <FAQItem question="What is Keymate?">
    Keymate is an enterprise authorization and IAM platform.
  </FAQItem>
  <FAQItem question="Which access control models are supported?">
    Keymate supports RBAC, ABAC, and ReBAC models.
  </FAQItem>
</FAQ>

What is Keymate?

Keymate is an enterprise authorization and IAM platform that provides fine-grained access control for modern applications.

Which access control models are supported?

Keymate supports RBAC, ABAC, and ReBAC models — either individually or combined.

How do I get started?

Check out the Getting Started section for installation and setup instructions.

SEO Best Practices​

Code Blocks​

Basic Syntax Highlighting​

Supported Languages​

Title and Line Highlighting​

Multi-language Tabs​

Mermaid Diagrams​

Sequence Diagram​

Flowchart​

Architecture Diagram​

Images​

Image Standards​

File Format​

Resolution and Size​

File Naming​

File Location​

Screenshot Capture Rules​

Alt Text​

Annotations​

CDN Image (Blob Storage)​

CDN Image with Custom Width​

External Image (No CDN)​

Local Image (No CDN)​

Image with Caption​

Image Grid​

Video​

Cards​

Single Card​

Card Grid​

🔐Authorization

🏗️Architecture

🔌Integrations

Admonitions​

Tables​

Links​

Internal Links​

External Links​

Details / Collapsible Sections​

Page Templates​

FAQ​

SEO Best Practices

Code Blocks

Basic Syntax Highlighting

Supported Languages

Title and Line Highlighting

Multi-language Tabs

Mermaid Diagrams

Sequence Diagram

Flowchart

Architecture Diagram

Images

Image Standards

File Format

Resolution and Size

File Naming

File Location

Screenshot Capture Rules

Alt Text

Annotations

CDN Image (Blob Storage)

CDN Image with Custom Width

External Image (No CDN)

Local Image (No CDN)

Image with Caption

Image Grid

Video

Cards

Single Card

Card Grid

Admonitions

Tables

Links

Internal Links

External Links

Details / Collapsible Sections

Page Templates

FAQ