# Writing style and page kit

The site has three readers: **partners and prospects** (operators, game
providers, affiliates, reward partners), **investors and advisors**, and the
**internal team**. Public pages serve the first two and must be good enough to
send to a prospect as-is.

## Voice

- Plain, confident, specific. Second person for guides ("you send…"), third
  person for product pages ("PlayerPal links…").
- Lead with what the reader gets, then how. One idea per paragraph, 1–4
  sentences. Prefer tables, steps and diagrams to long prose.
- No hype words (revolutionary, seamless, cutting-edge, best-in-class), no
  exclamation marks, no emoji in prose.
- British-neutral spelling as used in the repo (behaviour, authorisation is
  fine either way; be consistent within a page). Use the glossary terms:
  Player, Account, Operator, Game provider, Affiliate, Reward partner, Link,
  Unlink, Audience, Alias, Activity, Points.
- Never invent product behaviour, pricing, commercial terms, SLAs, legal
  conclusions, certifications, customer names or numbers. If the repo does not
  say it, leave it out or say "contact PlayerPal" / "not yet decided".

## Status labels

Readers see three labels. Front matter keeps the precise value:

| Front matter `status` | Reader label | Meaning |
|---|---|---|
| `implemented` | Available | Built and tested in the platform |
| `in-progress` | In development | Being built; behaviour may change. Add `demo: true` if it exists only as demo code |
| `proposed` | Planned | Designed or decided, not built yet |

Inline: `[In development]`. On a page that mixes statuses, give
each section its own `<Status … />` right under the heading. A mockup or demo
UI never makes something Available.

## Public pages

Front matter `audience: public`. In addition to the rules above:

1. **No links into the repository** (source files, ADRs, internal pages). The
   public build fails on them. Link only to other public pages (relative
   `.mdx` paths) or to the API reference at `/api/partner`.
2. **Keep evidence in MDX comments**, invisible to readers but reviewable:
   ``
   under each claim-heavy section. HTML comments (`<!-- -->`) do not work in
   MDX.
3. **No internals**: no hostnames, IPs, cloud vendors, cluster or database
   details, environment variable names, seeded or demo IDs, internal team
   process, known bugs or code-level discrepancies. Describe behaviour and
   guarantees, not implementation. Known gaps that affect partners are stated
   as product status ("In development", "Planned"), not as bugs.
4. Examples use placeholders (`pp_kid_XXXX`, `<your-secret>`) and paths only
   (`POST /v1/ingest`). If a full URL is unavoidable, use
   `https://<playerpal-api-host>`. Never a real or made-up hostname.

## Page kit (MDX)

New pages are `.mdx`. These components are available on every page without
imports:

```mdx

  - [Link players](./linking-players.mdx): 
    Connect a casino account to PlayerPal without sharing personal data.
  

  
### Get credentials
…
  
### Sign a request
…

  
**curl**
…code block…
  
**Node.js**
…code block…

[Available]
```

Admonitions: `:::note`, `:::tip`, `:::info`, `:::warning`, `:::danger`, with
an optional title: `:::info[In development]`. Diagrams: ` ```mermaid `
fences (flowchart, sequenceDiagram, stateDiagram-v2).

MDX pitfalls: a bare `<` or `{` in prose breaks the build. Write `&lt;`, use
backticks (`` `a < b` ``), or put it in a code block. Leave a blank line
before and after JSX blocks and inside `<TabItem>` around code fences.

## Developer guide kit

Developer guides use a two-column layout: prose on the left, a sticky code
column on the right. Add `wide: true` and `hide_table_of_contents: true` to
the front matter, then:

```mdx

## Send your first batch

`ingestSubmit` (see the API reference)

Prose, lists and tables for this step.

(Parameter table: see the API reference.)

What the reader should see now.

(Code sample: send-batch. See the page for curl, Node.js, Python, PHP, Java and C#.)

Response:

```
{ "replayed": false }
```

```

- `Endpoint` and `Params` read the generated partner OpenAPI document by
  `operationId`, so they always match the code. `Params` takes
  `in="body" | "query" | "path" | "header" | "response"`.
- `Sample` shows a named region (`docs:start <name>` … `docs:end <name>`) of
  the files in `docs-site/samples/signing/` in six languages, with a language
  choice remembered across the site. Those files run against the HMAC test
  vectors in CI (`npm run check:samples`), so change code there, never inline.
- `Example` is for static payloads such as responses and errors; pass the
  text as a template literal so MDX does not parse it.
- `Explainer` is a short animated walkthrough (scenes with play, pause and
  scrub). Pick one with `id`: `<Explainer id="linking" />`. The ids are in
  `docs-site/src/components/explainer/registry.ts`. Each explainer is
  hand-built in `explainers/`, so its values must match the sources its page
  cites; the signing values live in `data.ts` and must match the test vectors.
  Use one per concept, near the top of its page, and give it an evidence
  comment like any other claim. Add scenes in the explainer's file. Each scene
  is a pure function of its progress, so keep it that way.

## Page template

```mdx
---
title: Link players                 # short, task-shaped
description: One sentence that works as a search snippet.
sidebar_label: Linking players      # optional
status: implemented
audience: public
verified: <commit>
---

# Link players

One-paragraph summary: what this does for the reader and when to use it.

## How it works        (diagram or steps)
## Before you start    (prerequisites)
## Step by step / Reference
## Errors and edge cases
## Related             (2–4 cards or links)
```

Aim for 80–220 lines. Every public page ends with a short Related section.