Create README.md

README.md

@@ -0,0 +1,144 @@
+# YAML block scalars: an OpenAPI cheat sheet
+
+Markdown (CommonMark) is supported on OpenAPI fields like `summary`, `description`, `externalDocs.description`, schema/parameter/response `description`, etc.
+
+And the situations to use each Scalar type can be a bit confusing if you don't do it everyday.
+
+## The types of Scalar
+
+* `>` **Folded (prose)** — single newlines become spaces; blank lines = paragraph breaks. Best default for paragraphs.
+* `|` **Literal (layout-sensitive)** — keep newlines exactly. Use for lists you want hard breaks, tables, or code you want untouched.
+
+### Modifiers
+
+* Add `-` to strip the final newline (`>-`, `|-`) to avoid trailing EOLs.
+* Add `+` to keep all trailing newlines (`>+`, `|+`) if you *need* them.
+
+## Notes
+* Single newline = **space** (no hard break). Use two spaces + newline **or** a blank line for a real break.
+* Blank line separates paragraphs.
+* Lists usually need a blank line before them for consistent rendering.
+* Code: use fenced blocks ``` for best results.
+
+## Prescriptions & examples
+
+**1) Long paragraphs (default choice)**
+
+```yaml
+description: >-
+  Returns a list of orders filtered by status and date.
+  Handles pagination and sorting.
+````
+
+**Rendered preview:**
+
+> Returns a list of orders filtered by status and date. Handles pagination and sorting.
+
+---
+
+**2) Bullet lists (preserve structure)**
+
+```yaml
+description: |
+  **Features**
+  - Fast
+  - Safe
+  - Boring
+```
+
+**Rendered preview:**
+
+> **Features**
+>
+> * Fast
+> * Safe
+> * Boring
+
+---
+
+**3) Paragraphs + list (mix)**
+
+```yaml
+description: |
+  Use this endpoint to manage orders.
+
+  **Parameters**
+  - `limit` — max items
+  - `cursor` — pagination token
+```
+
+**Rendered preview:**
+
+> Use this endpoint to manage orders.
+>
+> **Parameters**
+>
+> * `limit` — max items
+> * `cursor` — pagination token
+
+---
+
+**4) Code examples (literal or fenced)**
+
+````yaml
+description: |
+  Example:
+  ```bash
+  curl -H "Authorization: Bearer <token>" /orders
+  ```
+````
+
+**Rendered preview:**
+
+> Example:
+>
+> ```bash
+> curl -H "Authorization: Bearer <token>" /orders
+> ```
+
+---
+
+**5) Tables (avoid folding that might reflow pipes)**
+
+```yaml
+description: |
+  | Field | Type    | Notes      |
+  |------:|:-------:|------------|
+  | id    | string  | required   |
+  | total | number  | USD cents  |
+```
+
+**Rendered preview:**
+
+> | Field |  Type  | Notes     |
+> | ----: | :----: | --------- |
+> |    id | string | required  |
+> | total | number | USD cents |
+
+---
+
+**6) Multi-paragraph prose with soft wraps**
+
+```yaml
+description: >
+  The export job runs asynchronously and may take several minutes.
+
+  Use the `GET /jobs/{id}` endpoint to poll status.
+```
+
+**Rendered preview:**
+
+> The export job runs asynchronously and may take several minutes.
+>
+> Use the `GET /jobs/{id}` endpoint to poll status.
+
+---
+
+## TL;DR
+
+| Scenario                                      | Symbols | Meaning (newline behavior)                                                |
+| --------------------------------------------- | ------- | ------------------------------------------------------------------------- |
+| Prose paragraph                               | >       | **Folded + clip** — single newlines → spaces; keep **one** final newline. |
+| Prose paragraph, no trailing `\n`             | >-      | **Folded + strip** — single newlines → spaces; **no** final newline.      |
+| Preserve manual line breaks                   | |       | **Literal + clip** — keep all line breaks; keep **one** final newline.    |
+| Preserve manual line breaks, no trailing `\n` | |-      | **Literal + strip** — keep all line breaks; **no** final newline.         |