> ## Documentation Index
> Fetch the complete documentation index at: https://legal.belang.org/llms.txt
> Use this file to discover all available pages before exploring further.

# Drafting

# Drafting: anatomie en regels

Interne richtlijn voor hoe we Voorwaarden opbouwen. Korter is beter.

## Hiërarchie

```
Instrument (opties, obligaties, certificaten, sars, ...)
 └── Voorwaarden
      └── Artikel            # één bestand, één onderwerp
           └── Clausule      # één bepaling, één alinea-idee
                └── Term     # gedefinieerd in Artikel 1
```

* **Artikel = één verantwoordelijkheid.** Als een artikel "X en Y" heet, splits.
* **Clausule = één regel.** Eén kop (`####`), één gedachte. Combineer niet.
* **Termen** krijgen hun definitie in Artikel 1 en worden overal hetzelfde gespeld (hoofdletter voor gedefinieerde termen: `Uitgever`, `Optiehouder`).

## Typografie

* **Geen emdashes** (`—`) of en-dashes (`–`). Gebruik komma's, dubbele punten of haakjes voor de bijzin. Reden: oogt AI-gegenereerd en is lastig te typen voor co-auteurs.
* **Geen smart quotes** in nieuwe tekst (`"` i.p.v. `" "`).

## Terminologie (overal gelijk)

| Concept | Term |
| - | - |
| Uitgifte van het instrument | **Uitgifte** (niet "Toekenning") |
| Overdracht aan derde | **Overdracht** (enkelvoud) |
| Partij die uitgeeft | **Uitgever** |
| Partij die houdt | **Optiehouder**, **Obligatiehouder** of **Certificaathouder** |
| Datum van uitgifte | **Uitgiftedatum** |

Nieuw concept? Kies eerst een term die al elders gebruikt wordt. Alleen nieuw invoeren als echt nodig.

## Artikel-patroon

Elk artikel-bestand (`<instrument>/voorwaarden/<artikel>.mdx`):

1. Frontmatter: `title` (identiek aan hoe het in de sidebar heet, zonder "Artikel N")
2. Clausules als `#### Kop` + één korte alinea
3. Geen proza-inleiding; geen afsluitende conclusie
4. Verwijzingen naar andere artikelen: markdown-links, geen MDX-magie

## Snippets (her)gebruik

Opties gebruikt modular snippets in `/snippets/<artikel>/<slug>.mdx`. Waarom:

* **Compleet voorbeeld** is gegenereerd uit dezelfde snippets → geen inhoud dupliceren
* **Varianten** (good leaver / bad leaver / etc.) kunnen later naast elkaar bestaan zonder copy-paste

Snippet-file conventie:

```mdx theme={null}
---
title: "Korte titel van de clausule"
---

De clausule-tekst, pure markdown.
```

Nieuwe snippets: pure markdown in body, geen JSX. Metadata gaat in frontmatter.

## Compleet voorbeeld

* Live pagina = alleen banner + download-link (geen inline render, anders duplicatie in search)
* `scripts/build-voorbeeld.mjs` genereert één `.md` vanuit een template in `scripts/templates/` die de snippets importeert
* Template wijzigt mee met de artikelstructuur; regenereer na wijzigingen

## Clause-bank artefact (voor externe consumenten, bv. de drafter op app.belang.org/tooling/documents)

* `scripts/build-clauses.mjs` resolvet snippets (verbatim) en schrijft per
  `product × taal` geresolveerde artikel-`.md`'s + een `manifest.json` naar
  `dist/clauses/` (gitignored; build-only artefact).
* Product/taal/artikel-volgorde komt uit `docs.json` (zelfde nav als de site),
  dus het loopt niet uit de pas met wat gepubliceerd wordt.
* Bron van waarheid blijft de MDX hier; consumenten pinnen een versie
  (`manifest.banks[].version`/`hash` + `sourceCommit`) en pullen het artefact.
* Body's worden VERBATIM gesliced (geen markdown-reparse), zodat notatie in de
  clausule-tekst exact meekomt.

## Nummering

Artikel-niveau: `## Artikel N - Titel` (alleen in de template).
Clausule-niveau: `#### Titel` (snippets) of `#### N.M Titel` (alleen in template, met nummering).

## Redirects

Hernoem je een pad? Voeg een redirect toe in `docs.json` onder `"redirects"`. Nooit stilletjes verplaatsen.

## Wat we (nu) niet doen

* Geen versie-tags per clausule (komt later, zie data-structuur discussie)
* Geen varianten in één snippet; elke variant krijgt zijn eigen snippet-file
* Geen taal-specifieke content in snippet-bodies; vertalingen in `/snippets/en/...`


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.