> ## 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.

# Citations

> CSL-JSON citations and automatic bibliography generation

Citations allow you to reference sources in your document and automatically generate a formatted bibliography. Autype uses the [CSL-JSON](https://citeproc-js.readthedocs.io/en/latest/csl-json/markup.html) standard for citation data.

## Defining citations

The top-level `citations` array contains citation entries in CSL-JSON format. Each entry represents a single source (book, article, webpage, etc.).

```json theme={null}
{
  "citations": [
    {
      "id": "smith2023",
      "type": "book",
      "title": "Modern Document Automation",
      "author": [
        { "family": "Smith", "given": "John" }
      ],
      "issued": { "date-parts": [[2023]] },
      "publisher": "Tech Press",
      "publisher-place": "New York"
    },
    {
      "id": "doe2024",
      "type": "article-journal",
      "title": "Advances in PDF Generation",
      "author": [
        { "family": "Doe", "given": "Jane" },
        { "family": "Miller", "given": "Bob" }
      ],
      "issued": { "date-parts": [[2024, 3]] },
      "container-title": "Journal of Document Engineering",
      "volume": "12",
      "issue": "3",
      "page": "45-67",
      "DOI": "10.1234/jde.2024.001"
    }
  ]
}
```

<Info>
  The `citations` array supports up to 1000 entries.
</Info>

## CSL-JSON item properties

Every citation entry requires `id` and `type`. All other fields are optional.

### Required fields

| Property | Type   | Description                                                                                                       |
| -------- | ------ | ----------------------------------------------------------------------------------------------------------------- |
| `id`     | string | Unique identifier for the citation (e.g., `"smith2023"`). Used to reference the citation in text. Max: 100 chars. |
| `type`   | string | Item type. See [supported types](#supported-item-types) below.                                                    |

### Names (authors, editors, etc.)

Name fields accept an array of name objects:

```json theme={null}
{
  "author": [
    { "family": "Smith", "given": "John" },
    { "family": "van Beethoven", "given": "Ludwig", "non-dropping-particle": "van" },
    { "literal": "World Health Organization" }
  ]
}
```

| Property                | Type   | Description                                                               |
| ----------------------- | ------ | ------------------------------------------------------------------------- |
| `family`                | string | Family name / surname. Max: 200 chars.                                    |
| `given`                 | string | Given name / first name. Max: 200 chars.                                  |
| `dropping-particle`     | string | Particle dropped when sorting (e.g., "de" in some styles). Max: 50 chars. |
| `non-dropping-particle` | string | Particle kept when sorting (e.g., "van"). Max: 50 chars.                  |
| `suffix`                | string | Name suffix (e.g., "Jr.", "III"). Max: 50 chars.                          |
| `literal`               | string | Literal name string for institutional authors. Max: 500 chars.            |

**Available name fields:** `author`, `editor`, `translator`, `collection-editor`, `composer`, `container-author`, `director`, `editorial-director`, `illustrator`, `interviewer`, `original-author`, `recipient`, `reviewed-author`

### Dates

Date fields use the CSL-JSON date format:

```json theme={null}
{
  "issued": { "date-parts": [[2024, 3, 15]] },
  "accessed": { "date-parts": [[2024, 6, 1]] }
}
```

| Property     | Type              | Description                                                               |
| ------------ | ----------------- | ------------------------------------------------------------------------- |
| `date-parts` | array             | Array of date arrays: `[[year, month, day]]`. Month and day are optional. |
| `literal`    | string            | Literal date string (e.g., `"Spring 2024"`). Max: 200 chars.              |
| `raw`        | string            | Raw date string for parsing. Max: 200 chars.                              |
| `season`     | string \| number  | Season identifier.                                                        |
| `circa`      | boolean \| string | Approximate date flag.                                                    |

**Available date fields:** `issued`, `accessed`, `event-date`, `original-date`, `submitted`

### Titles

| Property                | Type   | Description                                                   |
| ----------------------- | ------ | ------------------------------------------------------------- |
| `title`                 | string | Title of the work. Max: 1000 chars.                           |
| `title-short`           | string | Short title. Max: 500 chars.                                  |
| `container-title`       | string | Title of the container (journal, book, etc.). Max: 500 chars. |
| `container-title-short` | string | Short container title. Max: 200 chars.                        |
| `collection-title`      | string | Title of the collection/series. Max: 500 chars.               |
| `original-title`        | string | Original title (for translations). Max: 500 chars.            |
| `reviewed-title`        | string | Title of the reviewed work. Max: 500 chars.                   |

### Numbers

| Property          | Type             | Description                                   |
| ----------------- | ---------------- | --------------------------------------------- |
| `volume`          | string \| number | Volume number.                                |
| `issue`           | string \| number | Issue number.                                 |
| `page`            | string           | Page range (e.g., `"45-67"`). Max: 100 chars. |
| `page-first`      | string \| number | First page.                                   |
| `number-of-pages` | string \| number | Total pages.                                  |
| `edition`         | string \| number | Edition number.                               |
| `version`         | string \| number | Version number.                               |
| `chapter-number`  | string \| number | Chapter number.                               |

### Identifiers

| Property | Type   | Description                                          |
| -------- | ------ | ---------------------------------------------------- |
| `DOI`    | string | Digital Object Identifier. Max: 200 chars.           |
| `ISBN`   | string | International Standard Book Number. Max: 50 chars.   |
| `ISSN`   | string | International Standard Serial Number. Max: 50 chars. |
| `PMID`   | string | PubMed ID. Max: 50 chars.                            |
| `PMCID`  | string | PubMed Central ID. Max: 50 chars.                    |
| `URL`    | string | Web URL. Max: 2000 chars.                            |

### Publisher

| Property          | Type   | Description                           |
| ----------------- | ------ | ------------------------------------- |
| `publisher`       | string | Publisher name. Max: 500 chars.       |
| `publisher-place` | string | Place of publication. Max: 200 chars. |

### Other fields

| Property      | Type   | Description                                         |
| ------------- | ------ | --------------------------------------------------- |
| `abstract`    | string | Abstract text. Max: 5000 chars.                     |
| `language`    | string | Language of the work. Max: 50 chars.                |
| `genre`       | string | Genre or type description. Max: 200 chars.          |
| `keyword`     | string | Keywords. Max: 500 chars.                           |
| `note`        | string | Additional notes. Max: 2000 chars.                  |
| `event`       | string | Event name (for conference papers). Max: 500 chars. |
| `event-place` | string | Event location. Max: 200 chars.                     |

## Supported item types

<Accordion title="All supported CSL-JSON item types">
  `article`, `article-journal`, `article-magazine`, `article-newspaper`, `bill`, `book`, `broadcast`, `chapter`, `classic`, `collection`, `dataset`, `document`, `entry`, `entry-dictionary`, `entry-encyclopedia`, `event`, `figure`, `graphic`, `hearing`, `interview`, `legal_case`, `legislation`, `manuscript`, `map`, `motion_picture`, `musical_score`, `pamphlet`, `paper-conference`, `patent`, `performance`, `periodical`, `personal_communication`, `post`, `post-weblog`, `regulation`, `report`, `review`, `review-book`, `software`, `song`, `speech`, `standard`, `thesis`, `treaty`, `webpage`
</Accordion>

## Using citations in sections

To cite a source in your text content, use the `@[citeKey]` syntax where `citeKey` matches the `id` of a citation entry.

### Basic citation

```json theme={null}
{ "type": "text", "text": "Document automation is evolving rapidly @[smith2023]." }
```

The `@[citeKey]` reference is replaced with the formatted in-text citation according to the configured `citationStyle` (e.g., `(Smith, 2023)` for APA7, `[1]` for IEEE).

### Citation with locators

Add a locator after the cite key, separated by a comma:

```json theme={null}
{ "type": "text", "text": "See @[smith2023, p. 42] for details." }
{ "type": "text", "text": "Discussed in @[doe2024, pp. 10-15]." }
{ "type": "text", "text": "See @[smith2023, ch. 3] and @[doe2024, sec. 2.1]." }
{ "type": "text", "text": "In @[smith2023, vol. 2, p. 42, note=\"emphasis added\"]." }
```

| 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="text"`                | `@[smith2023, note="emphasis added"]` |

Multiple locators can be combined: `@[smith2023, vol. 2, p. 42]`

### Suppress author / author only

| Syntax          | Description                  | Rendered (APA7) |
| --------------- | ---------------------------- | --------------- |
| `@[smith2023]`  | Normal citation              | (Smith, 2023)   |
| `@[-smith2023]` | Suppress author (prefix `-`) | (2023)          |
| `@[smith2023!]` | Author only (suffix `!`)     | Smith           |

```json theme={null}
{ "type": "text", "text": "@[smith2023!] argues that automation is key @[-smith2023, p. 42]." }
```

This renders as: "Smith argues that automation is key (2023, p. 42)."

### Multiple citations

Place multiple `@[...]` references next to each other:

```json theme={null}
{ "type": "text", "text": "Multiple sources support this claim @[smith2023] @[doe2024]." }
```

<Info>
  The `@[citeKey]` syntax works in all text content: headings, paragraphs (`text`, `text2`), list items, and table cells. It also works inside formatted text like `**bold @[smith2023] text**`.
</Info>

<Warning>
  When using `?strict=true` on the render endpoint, any `@[citeKey]` reference to a citation that is **not defined** in the `citations` array will cause a validation error. Without strict mode, undefined citations produce warnings but do not block rendering.
</Warning>

## Citation styles

The citation formatting style is configured via `defaults.citationStyle`:

```json theme={null}
{
  "defaults": {
    "citationStyle": "apa7"
  }
}
```

| Style       | In-text format   | Description              |
| ----------- | ---------------- | ------------------------ |
| `apa7`      | (Smith, 2023)    | APA 7th Edition          |
| `harvard`   | (Smith 2023)     | Harvard style            |
| `ieee`      | \[1]             | IEEE numbered style      |
| `chicago`   | (Smith 2023, 42) | Chicago author-date      |
| `mla`       | (Smith 42)       | MLA style                |
| `vancouver` | (1)              | Vancouver numbered style |

## Bibliography element

To render the formatted bibliography, add a `bibliography` element to a section:

```json theme={null}
{
  "type": "bibliography",
  "title": "References",
  "fontFamily": "Times New Roman",
  "fontSize": 18
}
```

### Properties

| Property     | Type   | Required | Default | Description                                                                                      |
| ------------ | ------ | -------- | ------- | ------------------------------------------------------------------------------------------------ |
| `type`       | string | **Yes**  | —       | Must be `"bibliography"`                                                                         |
| `id`         | string | No       | —       | Optional unique identifier. Max: 100 chars.                                                      |
| `title`      | string | No       | —       | Title displayed above the bibliography (e.g., `"References"`, `"Bibliography"`). Max: 200 chars. |
| `fontFamily` | string | No       | —       | Font family for the title. Max: 100 chars.                                                       |
| `fontSize`   | number | No       | —       | Font size for the title in pt (6–72).                                                            |
| `spacing`    | object | No       | —       | Spacing override with `before` and `after` in pt (0–100).                                        |

## Defaults for citations

### Bibliography style

Customize the bibliography appearance via `defaults.styles.bibliography`:

```json theme={null}
{
  "defaults": {
    "citationStyle": "apa7",
    "styles": {
      "bibliography": {
        "fontFamily": "Times New Roman",
        "fontSize": 11,
        "fontWeight": "normal",
        "color": "#000000",
        "hangingIndent": 1.27,
        "lineSpacing": 1.5,
        "entrySpacing": 6
      }
    }
  }
}
```

| Property        | Type   | Default | Description                                           |
| --------------- | ------ | ------- | ----------------------------------------------------- |
| `fontFamily`    | string | —       | Font family for bibliography entries. Max: 100 chars. |
| `fontSize`      | number | —       | Font size in pt (6–72).                               |
| `fontWeight`    | string | —       | Font weight: `"normal"` or `"bold"`                   |
| `color`         | string | —       | Text color in hex format (`#RGB` or `#RRGGBB`).       |
| `hangingIndent` | number | —       | Hanging indent for entries in cm (0–5).               |
| `lineSpacing`   | number | —       | Line spacing within entries (1–3).                    |
| `entrySpacing`  | number | —       | Space between entries in pt (0–50).                   |

## Complete example

```json theme={null}
{
  "document": { "type": "pdf", "size": "A4" },
  "citations": [
    {
      "id": "smith2023",
      "type": "book",
      "title": "Modern Document Automation",
      "author": [{ "family": "Smith", "given": "John" }],
      "issued": { "date-parts": [[2023]] },
      "publisher": "Tech Press"
    },
    {
      "id": "doe2024",
      "type": "article-journal",
      "title": "Advances in PDF Generation",
      "author": [{ "family": "Doe", "given": "Jane" }],
      "issued": { "date-parts": [[2024, 3]] },
      "container-title": "Journal of Document Engineering",
      "volume": "12",
      "page": "45-67"
    }
  ],
  "defaults": {
    "citationStyle": "apa7",
    "styles": {
      "bibliography": {
        "fontSize": 10,
        "hangingIndent": 1.27
      }
    }
  },
  "sections": [
    {
      "type": "flow",
      "content": [
        { "type": "h1", "text": "Introduction" },
        { "type": "text", "text": "@[smith2023!] describes how document automation is evolving rapidly @[-smith2023]. Recent advances in PDF generation @[doe2024, pp. 50-67] have made it possible to produce high-quality documents at scale." },
        { "type": "text", "text": "Both approaches @[smith2023] @[doe2024] demonstrate significant improvements over traditional methods." },
        { "type": "pageBreak" },
        { "type": "bibliography", "title": "References" }
      ]
    }
  ]
}
```