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

# Macros for Text: Built-in and Custom Macros for Auto Text Replacement

> Learn about built-in and custom macros for auto text replacement in PDF.co, including usage in integrations and custom data.

You can use built-in and custom macros inside text when using the [`/pdf/edit/add`](/pdf/edit/add) endpoint or the **Fill PDF** and **Add Text and Images to PDF** modules in [Zapier](../integrations/zapier/add-text-to-pdf), [Make](../integrations/make/add-text-images-formfields-to-pdf), and other integrations.

Macros may look like this: `{{$$newLine}}`, `[[$$newLine]]`, or `{{object.property}}` (when referencing custom data from JSON).

## Built-in Macros

Built-in macros always use the `$$` prefix.

**Available built-in macros:**

<Tabs>
  <Tab title="Current Page Number">
    Inserts the current page number, starting from 1.

    ```text theme={null}
    {{$$PageNumber}}
    ```
  </Tab>

  <Tab title="Total Page Count">
    Displays the total number of pages as text.

    ```text theme={null}
    {{$$PageCount}}
    ```
  </Tab>

  <Tab title="New Line">
    Adds a line break at the specified position.

    ```text theme={null}
    {{$$newLine}}
    ```
  </Tab>
</Tabs>

## Special Macro Style: Square Brackets

Some automation platforms like **n8n**, **Make.com** and **Zapier** use `{{ ... }}` style macros for their own purposes. To avoid conflicts, you can use `[[ ... ]]` square brackets instead. Just add the command `##replaceSquareBracketsToCurlyBrackets##` at the beginning of the text (once per text block).

**Example**

<Columns cols={2}>
  <Card title="Use This Format">
    `##replaceSquareBracketsToCurlyBrackets##[[macro1]]`
  </Card>

  <Card title="It Will Render As">
    `{{macro1}}`
  </Card>
</Columns>

## Custom Macros

You can provide custom data as JSON in the `templateData` property. Then you can use data from this JSON as `{{name}}` or `{{object.property}}` macros (or as `[[name]]` or `[[object.property]]` if you [enabled square brackets to curly conversion](#special-macro-style%3A-square-brackets)).

<Tip>
  JSON loaded into `templateData` should be escaped (with `JSON.stringify(dataObject)` in JS). Escaping means every `"` is replaced with `\"` (most programming languages do this automatically).

  <Tabs>
    <Tab title="Escaped JSON" icon="correct">
      ```json theme={null}
      "templateData": "{ \"paid\": true, \"invoice_id\": \"0002\", \"total\": \"$999.99\" }"
      ```
    </Tab>

    <Tab title="Non-escaped JSON" icon="incorrect">
      ```json theme={null}
      "templateData": "{ 'paid': true, 'invoice_id': '0002', 'total': '$999.99' }"
      ```
    </Tab>
  </Tabs>
</Tip>

## `Example` Payload

<Note>To see the request size limits, please refer to the [Request Size Limits](/api-reference/url-input-and-request-limits#pdf-co-request-size).</Note>

```json theme={null}
{
  "url": "https://pdfco-test-files.s3.us-west-2.amazonaws.com/pdf-edit/sample.pdf",
  "templateData": "{ \"firstName\": \"John\",  \"lastName\": \"Doe\",  \"age\": 26,   \"address\": {        \"streetAddress\": \"Market Street\",  \"city\": \"San-Francisco\",        \"postalCode\": \"94100\"    },    \"phoneNumbers\": [        {            \"type\": \"iPhone\",            \"number\": \"0123-4567-8888\"        },        {            \"type\": \"home\",            \"number\": \"0123-4567-8910\"        }    ]}",
  "annotations": [
    {
      "text": "{{firstName}} {{lastName}}\n{{address.streetAddress}}{{$$newLine}}{{phoneNumbers[0].number}}",
      "x": 250,
      "y": 100,
      "width": 150,
      "height": 100,
      "size": 12,
      "pages": "0-",
      "type": "TextFieldMultiline",
      "id": "multiline1"
    },
    {
      "text": "##replaceSquareBracketsToCurlyBrackets##Company: [[firstName]][[$$NewLine]][[lastName]]",
      "x": 50,
      "y": 50,
      "size": 12,
      "pages": "0-"
    }
  ]
}
```

## Custom Pragma

You can disable HTML rendering support using a pragma at the beginning of the text.

## `Example` Payload

<Note>To see the request size limits, please refer to the [Request Size Limits](/api-reference/url-input-and-request-limits#pdf-co-request-size).</Note>

```json theme={null}
{
  "url": "https://pdfco-test-files.s3.us-west-2.amazonaws.com/pdf-edit/sample.pdf",
  "annotations": [
    {
      "text": "##disableHtmlFormatting##html formatting disabled: <b>bold</b>, <u>underline</u> and <i>italic</i> styles.",
      "x": 10,
      "y": 10,
      "size": 12,
      "pages": "0-"
    },
    {
      "text": "html formatting auto enabled: <b>bold</b>, <u>underline</u> and <i>italic</i> styles.",
      "x": 10,
      "y": 25,
      "size": 12,
      "pages": "0-"
    }
  ]
}
```