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

# Text Elements

> Headings, paragraphs, and inline text formatting

Text elements are the primary content building blocks. They include headings (`h1`–`h6`), paragraphs (`text`), and secondary text (`text2`).

## Headings (h1–h6)

Six heading levels for document structure. Headings are used for table of contents generation, heading numbering, and internal references.

```json theme={null}
{ "type": "h1", "text": "Chapter 1: Introduction" }
{ "type": "h2", "text": "1.1 Background", "color": "#333333" }
{ "type": "h3", "text": "1.1.1 History", "fontWeight": "normal" }
```

## Paragraphs (text, text2)

Normal paragraphs use `type: "text"`. Secondary/smaller text uses `type: "text2"` — useful for footnotes, captions, or fine print.

```json theme={null}
{ "type": "text", "text": "This is a normal paragraph with body text." }
{ "type": "text2", "text": "This is secondary text, typically rendered smaller." }
```

## Properties

All text element types (`h1`–`h6`, `text`, `text2`) share the same properties:

| Property     | Type   | Required | Default     | Description                                                                                                                            |
| ------------ | ------ | -------- | ----------- | -------------------------------------------------------------------------------------------------------------------------------------- |
| `type`       | string | **Yes**  | —           | Element type: `"h1"`, `"h2"`, `"h3"`, `"h4"`, `"h5"`, `"h6"`, `"text"`, or `"text2"`                                                   |
| `id`         | string | No       | auto        | Unique identifier. Auto-generated if not provided. Max: 100 chars.                                                                     |
| `text`       | string | **Yes**  | —           | Text content. Supports inline formatting (see below). 1–5000 chars.                                                                    |
| `fontFamily` | string | No       | `"Arial"`   | Font family override. Max: 100 chars.                                                                                                  |
| `fontSize`   | number | No       | `11`        | Font size in pt (6–72).                                                                                                                |
| `fontWeight` | string | No       | `"normal"`  | `"normal"` or `"bold"`                                                                                                                 |
| `align`      | string | No       | `"left"`    | Alignment: `"left"`, `"center"`, `"right"`, `"justify"`                                                                                |
| `color`      | string | No       | `"#000000"` | Text color in hex (`#RGB` or `#RRGGBB`).                                                                                               |
| `anchor`     | string | No       | —           | Anchor ID for internal references (**headings only**, ignored on `text`/`text2`). Pattern: `^[a-zA-Z][a-zA-Z0-9_-]*$`. Max: 100 chars. |
| `spacing`    | object | No       | —           | Spacing override with `before` and `after` in pt (0–100).                                                                              |

<Info>
  The defaults shown above (`"Arial"`, `11`, `"left"`, etc.) are the **built-in fallbacks**. In practice, values are resolved with a three-level cascade: **element property → element style** (from `defaults.styles.h1`, `defaults.styles.text`, etc.) **→ global defaults** (`defaults.fontFamily`, `defaults.fontSize`, `defaults.color`) **→ built-in fallback**.
</Info>

## Inline formatting

The `text` property supports inline formatting using an extended Markdown-like syntax. This is **not standard Markdown** — some syntax elements are Autype-specific.

### Text formatting

| Syntax               | Result            | Example                             |
| -------------------- | ----------------- | ----------------------------------- |
| `**text**`           | **Bold**          | `"This is **important**."`          |
| `*text*` or `_text_` | *Italic*          | `"This is *emphasized*."`           |
| `++text++`           | Underline         | `"This is ++underlined++."`         |
| `~~text~~`           | ~~Strikethrough~~ | `"This is ~~deleted~~."`            |
| `==text==`           | Highlight         | `"This is ==highlighted==."`        |
| `==text=={#FF0}`     | Colored highlight | `"This is ==important=={#FFCC00}."` |
| `` `code` ``         | Inline code       | ``"Use the `render()` function."``  |

<Info>
  Inline code (`` `...` ``) preserves its content as-is — no further formatting is parsed inside backticks.
</Info>

### Links and references

| Syntax                  | Description                      | Example                                               |
| ----------------------- | -------------------------------- | ----------------------------------------------------- |
| `[text](url)`           | External hyperlink               | `"Visit [Autype](https://autype.com)."`               |
| `[text](url "title")`   | Hyperlink with title             | `"See [docs](https://docs.autype.com \"API docs\")."` |
| `[text](#anchor)`       | Internal reference (custom text) | `"See [Chapter 1](#intro)."`                          |
| `[](#anchor)`           | Internal reference (auto)        | `"See [](#fig-arch) for details."`                    |
| `[Text {num}](#anchor)` | Internal reference (template)    | `"Refer to [Figure {num}](#fig-arch)."`               |

### Abbreviations, citations, and variables

| Syntax                  | Description                | Example                                    |
| ----------------------- | -------------------------- | ------------------------------------------ |
| `~ABK~`                 | Abbreviation reference     | `"The ~API~ uses ~REST~."`                 |
| `@[citeKey]`            | Citation                   | `"As shown by @[smith2023]."`              |
| `@[citeKey, p. 42]`     | Citation with page         | `"See @[smith2023, p. 42]."`               |
| `@[citeKey, pp. 10-15]` | Citation with page range   | `"Discussed in @[smith2023, pp. 10-15]."`  |
| `@[-citeKey]`           | Citation (suppress author) | `"As shown @[-smith2023]."` → `(2023)`     |
| `@[citeKey!]`           | Citation (author only)     | `"@[smith2023!] argues that..."` → `Smith` |
| `{{varName}}`           | Variable substitution      | `"Hello {{companyName}}!"`                 |

<Accordion title="Full citation locator options">
  Citations support the following locator options after the cite key, separated by commas:

  | Locator | Syntax                       | Example                                      |
  | ------- | ---------------------------- | -------------------------------------------- |
  | Page    | `p. 42` or `page 42`         | `@[smith2023, p. 42]`                        |
  | Pages   | `pp. 42-45` or `pages 42-45` | `@[smith2023, pp. 42-45]`                    |
  | Chapter | `ch. 3` or `chapter 3`       | `@[smith2023, ch. 3]`                        |
  | Section | `sec. 2.1` or `section 2.1`  | `@[smith2023, sec. 2.1]`                     |
  | Volume  | `vol. 2` or `volume 2`       | `@[smith2023, vol. 2]`                       |
  | Note    | `note="emphasis added"`      | `@[smith2023, p. 42, note="emphasis added"]` |

  Prefix `-` suppresses the author name, suffix `!` shows only the author name (narrative citation).
</Accordion>

### Combining formatting

Formatting marks can be nested. Abbreviations and citations work inside formatted text:

```json theme={null}
{
  "type": "text",
  "text": "This is **bold with ~API~ reference** and *italic with @[smith2023] citation*."
}
```

```json theme={null}
{
  "type": "text",
  "text": "Use ==highlighted text=={#FFCC00} and `` `inline code` `` together with ++underlined++ content."
}
```

## Anchors and internal references

Headings can define an `anchor` ID that other elements can reference. Images, charts, and tables can also define anchors (see their respective pages).

```json theme={null}
{
  "sections": [{
    "type": "flow",
    "content": [
      { "type": "h1", "text": "Introduction", "anchor": "intro" },
      { "type": "text", "text": "Some introductory text." },
      { "type": "image", "src": "https://example.com/arch.png", "caption": "Architecture", "anchor": "fig-arch" },
      { "type": "text", "text": "For background, see [Introduction](#intro)." }
    ]
  }]
}
```

### Internal reference display modes

There are three ways to reference an anchor:

| Syntax                      | Mode     | Rendered as                                                                              |
| --------------------------- | -------- | ---------------------------------------------------------------------------------------- |
| `[](#fig-arch)`             | Auto     | Automatically shows the target's caption with numbering (e.g., "Figure 1: Architecture") |
| `[Figure {num}](#fig-arch)` | Template | Replaces `{num}` with the target's number (e.g., "Figure 1")                             |
| `[see here](#fig-arch)`     | Custom   | Shows the provided text as a clickable link ("see here")                                 |

<Warning>
  Anchor IDs must be unique across the entire document. Duplicate anchors always cause a validation error. Broken references (pointing to non-existent anchors) cause errors only in strict mode (`?strict=true`).
</Warning>

## Defaults

Configure default styles for text elements via `defaults.styles`:

```json theme={null}
{
  "defaults": {
    "fontFamily": "Noto Sans",
    "fontSize": 11,
    "color": "#333333",
    "styles": {
      "h1": { "fontSize": 24, "fontWeight": "bold", "color": "#111111", "pageBreakBefore": true },
      "h2": { "fontSize": 18, "fontWeight": "bold" },
      "h3": { "fontSize": 14, "fontWeight": "bold" },
      "h4": { "fontSize": 12, "fontWeight": "bold" },
      "text": { "fontSize": 11, "align": "justify" },
      "text2": { "fontSize": 9, "color": "#666666" }
    }
  }
}
```

The `pageBreakBefore` property in a heading style forces a page break before every instance of that heading level — useful for starting each chapter on a new page.

## Supported fonts

The following fonts are guaranteed to be available in the rendering engine. Use these font family names in `fontFamily` properties.

<Warning>
  Using a font that is not installed in the render container will cause a **silent fallback** to the default font (`Arial`). Always use one of the listed fonts to ensure consistent output.
</Warning>

### Sans-serif

| Font           | Notes                                                  |
| -------------- | ------------------------------------------------------ |
| `Arial`        | Classic Microsoft sans-serif, widely used              |
| `Arial Black`  | Heavy weight display font                              |
| `Verdana`      | Highly readable, designed for screens                  |
| `Trebuchet MS` | Humanist sans-serif                                    |
| `Carlito`      | Metrically compatible with **Calibri**                 |
| `Roboto`       | Google's modern sans-serif                             |
| `Open Sans`    | Humanist sans-serif, great for body text               |
| `Lato`         | Warm, friendly sans-serif                              |
| `Noto Sans`    | Extensive language support (CJK, Arabic, Hebrew, etc.) |
| `DejaVu Sans`  | Extended Unicode coverage                              |

### Serif

| Font              | Notes                                  |
| ----------------- | -------------------------------------- |
| `Times New Roman` | Standard for academic documents        |
| `Georgia`         | Elegant serif for screen readability   |
| `Caladea`         | Metrically compatible with **Cambria** |
| `Roboto Slab`     | Slab serif companion to Roboto         |
| `Noto Serif`      | Extensive language support             |
| `DejaVu Serif`    | Extended Unicode coverage              |

### Monospace

| Font               | Notes                           |
| ------------------ | ------------------------------- |
| `Courier New`      | Classic monospace               |
| `Andale Mono`      | Clean monospace                 |
| `Noto Sans Mono`   | Monospace with language support |
| `DejaVu Sans Mono` | Extended Unicode monospace      |

### Display

| Font            | Notes                        |
| --------------- | ---------------------------- |
| `Comic Sans MS` | Casual, comic-style          |
| `Impact`        | Bold condensed for headlines |

<Info>
  **MS Office compatibility:** Calibri documents render correctly using `Carlito` (metrically identical). Cambria documents render correctly using `Caladea` (metrically identical). The render engine also has hundreds of Noto language-specific variants (e.g., `Noto Sans CJK JP`, `Noto Sans Arabic`, `Noto Serif Bengali`) installed for international document support.
</Info>

## Complete example

```json theme={null}
{
  "document": { "type": "pdf", "size": "A4" },
  "abbreviations": { "API": "Application Programming Interface" },
  "citations": [
    { "id": "smith2023", "type": "book", "title": "Document Automation", "author": [{ "family": "Smith", "given": "John" }], "issued": { "date-parts": [[2023]] } }
  ],
  "variables": { "companyName": "Acme Inc" },
  "defaults": {
    "fontFamily": "Noto Sans",
    "fontSize": 11,
    "styles": {
      "h1": { "fontSize": 22, "fontWeight": "bold" },
      "h2": { "fontSize": 16, "fontWeight": "bold" }
    }
  },
  "sections": [
    {
      "type": "flow",
      "content": [
        { "type": "h1", "text": "Welcome to {{companyName}}", "anchor": "welcome" },
        { "type": "text", "text": "This document was created by **{{companyName}}** using the ~API~." },
        { "type": "h2", "text": "Background", "anchor": "background" },
        { "type": "text", "text": "As described by @[smith2023, pp. 10-15], automation is key. See [Welcome](#welcome) for an overview." },
        { "type": "text", "text": "The ==key insight== is that the `render()` function processes documents efficiently." },
        { "type": "text", "text": "@[smith2023!] also argues that ++underlined++ and ~~deprecated~~ syntax should be supported." },
        { "type": "text2", "text": "Note: This is secondary text with smaller font size." },
        { "type": "h3", "text": "Sub-section" },
        { "type": "text", "text": "Content with *italic*, **bold with ~API~ inside**, and ++underlined++ formatting." }
      ]
    }
  ]
}
```