---
title: "Citations"
description: "Cite a bibliography entry of the Document with the inline cite node: insert it with /zitat, read it as (Autor Jahr), and keep it through Markdown export and import."
canonical_url: "https://skaile-ai.github.io/forge-editor/guides/citations"
---
# Citations

> Cite a bibliography entry of the Document with the inline cite node: insert it with /zitat, read it as (Autor Jahr), and keep it through Markdown export and import.

A **Cite** is an inline node (`cite`) that names one Bibliographic record of the Document by its citation key. The Bibliographic record is the CSL-JSON in `meta.bib` of a Typed block (a `paper`, a `document`, a `report`). The Cite shows the short form of that record, `(Autor Jahr)`, and, when it has a locator, `(Autor Jahr, S. 12)`.

A Cite is not a reference chip. The reference chip (`[@<block id>]`) points at a Block and shows its title or short citation; a Cite points at a Bibliographic record and always reads as a citation in running text. Both nodes live in the `composites` schema, because the Markdown export needs them on the server too.

## Insert a citation

Type `/zitat` (in the slash menu: „Zitat einfügen“) or type `[cite:` by hand. A picker lists the bibliography entries of the open Document: every Typed block with `meta.bib` whose short citation, full citation or citation key contains what you typed. Choose one and the Cite is inserted, followed by a space.

The Cite has the attributes `key` and `locator`:

<table>
<thead>
  <tr>
    <th>
      Attribute
    </th>
    
    <th>
      Meaning
    </th>
  </tr>
</thead>

<tbody>
  <tr>
    <td>
      <code>
        key
      </code>
    </td>
    
    <td>
      the citation key of the entry. It is the key that <code>
        bibtexOf
      </code>
      
       writes into the <code>
        .bib
      </code>
      
       entry: the first author's family name, the year and the first word of the title, in lowercase ASCII (<code>
        lecun2015deep
      </code>
      
      )
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        locator
      </code>
    </td>
    
    <td>
      the position inside the cited work (<code>
        S. 12
      </code>
      
      ); <code>
        null
      </code>
      
       cites the work as a whole
    </td>
  </tr>
</tbody>
</table>

The key is derived from the record. When two entries of one Document derive the same key, the first one in document order is the one a Cite resolves to.

## What the chip shows

The chip resolves its key against the entries of the Document on every change of the Document. It shows the short form from `citeShort` (`Doe 2024`, `Doe & Roe 2024`, `Doe et al. 2024`; the first 40 characters of the title when the entry has no author) and the full form from `citeFull` as its tooltip. If the author, the year or the title of the entry changes, the chip changes with it.

<table>
<thead>
  <tr>
    <th>
      Action
    </th>
    
    <th>
      Result
    </th>
  </tr>
</thead>

<tbody>
  <tr>
    <td>
      Click
    </td>
    
    <td>
      reveals the bibliography entry in the Document
    </td>
  </tr>
  
  <tr>
    <td>
      Double click or right click
    </td>
    
    <td>
      opens a field for the locator („Stelle“) in an editable editor
    </td>
  </tr>
  
  <tr>
    <td>
      Key without an entry
    </td>
    
    <td>
      the chip shows <code>
        (key)
      </code>
      
      , greyed and struck through, with the tooltip „Literaturangabe nicht gefunden“
    </td>
  </tr>
</tbody>
</table>

## Markdown

A Cite is written as `[cite:<key>]` or, with a locator, `[cite:<key>, <locator>]`. A `]` inside the locator is written `\]`.

```md
Deep learning works [cite:lecun2015deep, S. 12] and has been replicated [cite:doe2020other].
```

The token is not Pandoc's `[@key]`: `[@` belongs to the reference chip and to mentions. `[cite:` parses straight back into the node when Markdown is imported, edited in source mode or written by an AI; there is no second step that checks the key. A key that names no entry is kept and shows as a gone chip.

The Block index text of a Block that holds a Cite contains `[cite:<key>]`, so a search for the key finds the Block.

## Framework bindings

The Vue and React `compositeFeature` give the node its view (`CiteView`, also exported from `@skaile/forge-editor/composites/vue` and `@skaile/forge-editor/composites/react`). A binding that supplies no `cite` node view (`CompositeNodeViews.cite` is optional) shows the static form `(key, locator)`. Servers build their schema with `compositeSchemaExtensions()`, which includes the node.

<table>
<thead>
  <tr>
    <th>
      Export
    </th>
    
    <th>
      Use
    </th>
  </tr>
</thead>

<tbody>
  <tr>
    <td>
      <code>
        CiteNode
      </code>
      
      , <code>
        CITE_NODE
      </code>
      
      , <code>
        CITE_TRIGGER
      </code>
    </td>
    
    <td>
      the node, its name and the popup trigger <code>
        [cite:
      </code>
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        citeMarkdown
      </code>
      
      , <code>
        citeAttrsOf
      </code>
    </td>
    
    <td>
      the Markdown form of a Cite and its typed attributes
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        citeEntriesOf(doc)
      </code>
      
      , <code>
        resolveCite(editor, key)
      </code>
      
      , <code>
        citeText(label, locator)
      </code>
    </td>
    
    <td>
      the entries a Cite can name, what a Cite shows now, and the chip text
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        citeSuggestion(t)
      </code>
    </td>
    
    <td>
      the options of the <code>
        [cite:
      </code>
      
       popup
    </td>
  </tr>
</tbody>
</table>


## Sitemap

See the full [sitemap](https://skaile-ai.github.io/forge-editor/sitemap.md) for all pages.