How blocks work

A Chiltepin document is Markdown with fenced blocks. The fence language names the block type; its body supplies the content, usually as YAML.

## Request flow

```sequence
endpoint: { method: POST, path: /orders }
actors:
  - { id: client, name: Client }
  - { id: api, name: Orders API }
messages:
  - client -> api: POST /orders
  - api --> client: 201 Created
```

The rules

• Use a documented block type and its supported fields. Run chiltepin block <type> to read the installed schema and example.
• A heading directly above a block supplies its title. Avoid repeating it in a title field.
• Keep explanations in Markdown around the block. Use description or lede for short supporting text where the block supports those fields.
• Add an optional id when another block needs to reference it. IDs must be unique across the documents checked together.
• Run chiltepin check after editing. Fix errors and review warnings; see Validation.

Write less YAML

Some lists accept short forms alongside objects. These examples belong to different block types; use the form documented for the field you are editing.

# Sequence messages
messages:
  - client -> api: POST /orders
  - api --> client: 201 Created

# ERD columns
columns:
  - id uuid pk
  - org_id uuid fk
  - email text

# Glossary terms
terms:
  - SLO — the target the team commits to
  - Saga — a transaction split across services

callout and pullquote also accept plain text with inline Markdown:

```callout
Clients must send an **Idempotency-Key** header so retries can be deduplicated.
```

For quoting and indentation problems, see YAML pitfalls.

Let diagrams place themselves

For flow, c4, state, dfd, block, and felogic, supply nodes and edges to use automatic layout. The default direction is left to right. Set dir: TB for top to bottom.

To place nodes manually, give them col and row values. When all nodes have coordinates, those positions take precedence over dir.

Which blocks for which doc?

Start with the block that answers the reader's question. Add another when it explains something the first one does not.

Browse the block catalog to compare rendered examples, or use Templates for a complete starting document. Slide-specific blocks and layout are covered in Slides.