Chapter 4: Designing Pixel-Perfect PDFs

Resource Management

A pixel-perfect document rarely relies on text alone. Professional invoices, reports, and contracts require company logos, dynamic branding assets, and occasionally specialized fonts or vector graphics.

In Strucsta, the Render step acts as a self-contained environment. Every PDF generation step has its own isolated file system, managed directly through the Templates & Assets tab in the workflow editor.

The Assets Workspace

When you open the configuration for a PdfMaker step, you'll find the Templates & Assets tab. This workspace is divided into two main areas:

1. The File Explorer (Left): A list of all files associated with this specific step. Here you can upload new files, create new JSON documents, rename assets, and delete unused resources.
2. The Editor/Viewer (Right): A dynamic view that changes based on the type of file you have selected.

---

Managing Text Files (JSONC, SVG, HTML)

Strucsta includes a built-in code editor for text-based resources. If you select a file with a text extension (e.g., .txt, .json, .svg, .hbs, .html, .md, or .csv), it opens directly in the browser editor.

The Main Template

Your primary layout file is typically named template.txt or template.json. This is the entry point the engine looks for when the workflow executes.

Sub-Templates and Components

Because you can create new files directly in the UI via the Create New File button (the document icon with a plus), you can break massive layouts into smaller, manageable chunks. If your report has a complex header, you can store it in a separate JSON file and reference it, keeping your main template clean.

Editor Features:

• Auto-Save: Be sure to hit Save File after making manual adjustments.
• Rename & Delete: Click the vertical ellipsis (⋮) next to a filename to quickly rename or remove it.

---

Managing Binary Files (Images & Fonts)

Binary files—such as .png or .jpg images, or .ttf font files—cannot be edited directly in a text editor.

When you select a binary file in the explorer, the workspace displays a binary viewer. From here, you can use the Upload Replacement button. This is incredibly useful if a client updates their branding; you can swap the logo.png file directly without ever needing to touch or update your underlying JSONC template logic.

Referencing Images in Your Layout

Once an image is uploaded to your step's asset folder, it is immediately available to the pdfmake rendering engine. You do not need to deal with absolute server paths or base64 encoding strings manually.

To display an image in your PDF, reference its exact filename in your JSONC template:

{
  "content": [
    // Referencing an uploaded logo image
    {
      "image": "company_logo.png",
      "width": 150,
      "alignment": "center",
      "margin": [0, 0, 0, 20]
    },
    {
      "text": "Monthly Financial Report",
      "style": "header"
    }
  ]
}

---

Best Practices and System Limits

To keep your document generation lightning-fast and your pipelines secure, the resource manager enforces a few simple guardrails:

• 10 MB File Limit: The maximum size for any single uploaded asset is 10 MB. For PDFs, you should heavily compress images before uploading them. A 5 MB high-resolution photograph will drastically slow down the PDF generation process and inflate the final document size.
• 100 Files Per Step: A single Render step can hold up to 100 individual files. If you find yourself hitting this limit, you likely need to rethink your architecture or pass dynamic images (like user avatars) via Base64 strings from the Ingest step, rather than storing them statically.
• Flat Directory: Subfolders are not supported. Keep your filenames flat, descriptive, and clean (e.g., header-bg.png instead of assets/img/header-bg.png).