# File generators

**File generators** are invoked by [**actions**](https://learn.mechanic.dev/core/actions) to create new files, using options provided by the action, and handing the resulting file back to the action for further use. In this way, [**tasks**](https://learn.mechanic.dev/core/tasks) can make choices about what files to generate, and what to do with the results.

| File generator                                                                 | Purpose                                                                                |
| ------------------------------------------------------------------------------ | -------------------------------------------------------------------------------------- |
| [Base64](https://learn.mechanic.dev/core/actions/file-generators/base64)       | Decodes base64-encoded content, returning a file containing the results                |
| [PDF](https://learn.mechanic.dev/core/actions/file-generators/pdf)             | Renders HTML using a full Webkit browser, returning a PDF file of the results          |
| [Plaintext](https://learn.mechanic.dev/core/actions/file-generators/plaintext) | Allows defining file contents using a plain string, instead of a file generator object |
| [URL](https://learn.mechanic.dev/core/actions/file-generators/url)             | Downloads and returns a file                                                           |
| [ZIP](https://learn.mechanic.dev/core/actions/file-generators/zip)             | Accepts its own set of file generators, returning a ZIP archive of the results         |

## Maximum filesize

Generated files may each be a maximum of 20MB.

{% hint style="info" %}
"But why?", you may well ask!

Mechanic allows action run results to be fed back into the system ([via mechanic/actions/perform](https://learn.mechanic.dev/techniques/responding-to-action-results)). File generators usually end up having their resulting files represented in the action run results, and base64-encoding 20mb of binary data makes for a lot of JSON. We have to draw a line somewhere. :person\_shrugging:
{% endhint %}

## Object structure

File generator objects, like [action objects](https://learn.mechanic.dev/core/tasks/code/action-objects), are plain JSON objects each having a single key, and a single value. The object key specifies which file generator is to be invoked; the object value contains the options used for that generator.

```
{
  FILE_GENERATOR_TYPE: FILE_GENERATOR_OPTIONS
}
```

In practice, file generator objects are given as values in a larger JSON object, in which filenames are mapped to file generators.

{% hint style="info" %}
The [plaintext](https://learn.mechanic.dev/core/actions/file-generators/plaintext) file generator is invoked implicitly by supplying a string, instead of supplying the usual file generator object.
{% endhint %}

In the following example, a [Files](https://learn.mechanic.dev/core/actions/files) action is defined, mapping filenames (`"invoice.pdf"`, `"external.jpg"`, and `plain.txt`) to file generators (a PDF generator, a URL generator, and – implicitly – a plaintext generator). Note how the file generator invocation varies, based on the specific file generator in play.

```liquid
{% action "files" %}
  {
    "invoice.pdf": {
      "pdf": {
        "html": "<h1>Order #12345</h1>\n<p>It's due!</p>"
      }
    },
    "external.jpg": {
      "url": "https://upload.wikimedia.org/wikipedia/en/a/a9/Example.jpg"
    },
    "plain.txt": "This\nis\na\nmulti-line\nplaintext\nfile."
  }
{% endaction %}
```

## Supported actions

These are the Mechanic actions that support file generators.

| Action                                                 | Usage                                                                                            |
| ------------------------------------------------------ | ------------------------------------------------------------------------------------------------ |
| [Email](https://learn.mechanic.dev/core/actions/email) | Uses file generators to prepare email attachments                                                |
| [Files](https://learn.mechanic.dev/core/actions/files) | Uses file generators to prepare temporary URLs, from which the generated files can be downloaded |
| [FTP](https://learn.mechanic.dev/core/actions/ftp)     | Uses file generators to prepare FTP uploads                                                      |
| [HTTP](https://learn.mechanic.dev/core/actions/http)   | Adds generated files to a multipart/form-data HTTP request                                       |


---

# Agent Instructions: Querying This Documentation

If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://learn.mechanic.dev/core/actions/file-generators.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.