Skip to main content
Abbreviations let you define short forms (e.g., “API”) and their full text (e.g., “Application Programming Interface”). They can be automatically collected into a List of Abbreviations in your document.

​
Defining abbreviations

The top-level abbreviations object is a key-value map where each key is the short form and the value is the full text. 
{
  "abbreviations": {
    "API": "Application Programming Interface",
    "HTML": "Hypertext Markup Language",
    "CSS": "Cascading Style Sheets",
    "R&D": "Research and Development",
    "REST": "Representational State Transfer"
  }
}

​
Key format

Abbreviation keys (short forms) must:
  • Start with a letter (including Unicode letters like Ä, ö, Ü)
  • Contain only letters, digits, spaces, and the characters & _ - . , ( ) / ' "
  • Be 1–20 characters long

​
Value format

PropertyTypeConstraints
(value)stringFull text of the abbreviation. 1–200 characters.

​
Using abbreviations in sections

To mark an abbreviation in your text content, wrap the abbreviation key with tildes: ~ABK~. The abbreviation must be defined in the top-level abbreviations object. 
{
  "sections": [{
    "type": "flow",
    "content": [
      { "type": "text", "text": "The ~API~ uses ~JSON~ over ~HTTP~ for all requests." },
      { "type": "text", "text": "Our ~REST~ endpoints follow standard conventions." }
    ]
  }]
}
When rendered, ~API~ will display the abbreviation with a tooltip or annotation showing the full text “Application Programming Interface” (depending on the output format).
The ~ABK~ syntax works in all text content within sections: headings, paragraphs (text, text2), list items, and table cells.
When using ?strict=true on the render endpoint, any ~ABK~ reference to an abbreviation that is not defined in the abbreviations object will cause a validation error. Without strict mode, undefined abbreviations produce warnings but do not block rendering.

​
List of Abbreviations element

To render an automatic list of all defined abbreviations, add a listOfAbbreviations element to a section: 
{
  "type": "listOfAbbreviations",
  "title": "List of Abbreviations",
  "sortOrder": "alphabetical",
  "fontFamily": "Arial",
  "fontSize": 18
}

​
Properties

PropertyTypeRequiredDefaultDescription
typestringYes—Must be "listOfAbbreviations"
idstringNo—Optional unique identifier. Max: 100 chars.
titlestringNo—Title displayed above the list (e.g., "List of Abbreviations"). Max: 200 chars.
sortOrderstringNo"alphabetical"Sort order: "alphabetical" (by abbreviation key) or "document" (order of first appearance in document).
fontFamilystringNo—Font family for the title. Max: 100 chars.
fontSizenumberNo—Font size for the title in pt (6–72).
spacingobjectNo—Spacing override with before and after in pt (0–100).

​
Defaults for abbreviations

You can customize the appearance of the abbreviation list globally via defaults.styles.listOfAbbreviations: 
{
  "defaults": {
    "styles": {
      "listOfAbbreviations": {
        "fontFamily": "Arial",
        "fontSize": 11,
        "fontWeight": "normal",
        "color": "#333333",
        "sortOrder": "alphabetical",
        "separator": " - "
      }
    }
  }
}

​
List of Abbreviations style properties

PropertyTypeDefaultDescription
fontFamilystring—Font family for list entries. Max: 100 chars.
fontSizenumber—Font size in pt (6–72).
fontWeightstring—Font weight: "normal" or "bold"
colorstring—Text color in hex format (#RGB or #RRGGBB).
sortOrderstring"alphabetical"Default sort order: "alphabetical" or "appearance" (order of first use).
separatorstring" - "Separator between abbreviation and full text (e.g., " - ", ": ", " = "). Max: 10 chars.

​
Complete example

{
  "document": { "type": "pdf", "size": "A4" },
  "abbreviations": {
    "API": "Application Programming Interface",
    "REST": "Representational State Transfer",
    "JSON": "JavaScript Object Notation",
    "HTTP": "Hypertext Transfer Protocol"
  },
  "defaults": {
    "styles": {
      "listOfAbbreviations": {
        "fontSize": 10,
        "separator": ": ",
        "sortOrder": "alphabetical"
      }
    }
  },
  "sections": [
    {
      "type": "flow",
      "content": [
        { "type": "listOfAbbreviations", "title": "Abbreviations" },
        { "type": "pageBreak" },
        { "type": "h1", "text": "Introduction" },
        { "type": "text", "text": "This document describes a ~REST~ ~API~ that uses ~JSON~ over ~HTTP~ for all communication." },
        { "type": "text", "text": "The ~API~ supports multiple output formats including PDF and DOCX." }
      ]
    }
  ]
}