Assets

An Asset wraps a file — HTML, PDF, CSS, or image — for use in templates. Assets are the content layer: the raw document files, stylesheets, images, and HTML partials that templates reference.

HTML assets are authored in Handlebars (.hbs or .html) and rendered with the viewmodel produced by their referencing Template's data.transform. They can compose other HTML assets as partials and pull in CSS and image assets, forming a dependency tree. PDF assets wrap an existing fixed-layout PDF file. Each asset version is immutable once published.

YAML Format

apiVersion: signstack/v1beta2
kind: Asset

metadata:
  key: offer_letter_pdf
  version: 1.0.0
  name: Offer Letter (PDF)

spec:
  type: pdf
  file: ./files/offer_letter.pdf

apiVersion: signstack/v1beta2
kind: Asset

metadata:
  key: offer_letter_html
  version: 1.0.0
  name: Offer Letter (HTML)

spec:
  type: html
  file: ./html/offer_letter.hbs        # Required (or use `content:` for inline)

  partials:                            # Optional: HBS partials, available as {{> alias}}
    header: company_header@1.0.0
    footer: legal_footer@1.0.0
  styles:                              # Optional: CSS asset references (cascading order)
    - base_styles@1.0.0
    - corporate_theme@1.0.0
  images:                              # Optional: image asset references, available as {{images.alias}}
    logo: company_logo@1.0.0
  data:                                # Schema describing the viewmodel this HBS expects
    schema: offer_letter_viewmodel@1.0.0
  pdfSettings:                         # Optional: PDF rendering settings when this HBS renders to PDF
    paperSize: Letter                  # Letter, Legal, A4, A3

apiVersion: signstack/v1beta2
kind: Asset

metadata:
  key: company_logo
  version: 1.0.0
  name: Company Logo

spec:
  type: image
  file: ./images/logo.png

apiVersion: signstack/v1beta2
kind: Asset

metadata:
  key: corporate_theme
  version: 1.0.0
  name: Corporate Theme

spec:
  type: css
  file: ./styles/corporate.css

Spec Fields

Partials

Partials can be a simple asset reference or an object with a role mapping:

partials:
  # Simple reference
  header: company_header@1.0.0

  # With role mapping (maps partial's roles to parent context)
  employee_signature:
    asset: signature_block@1.0.0
    roleMap:
      signer: employee

Examples

PDF Asset

apiVersion: signstack/v1beta2
kind: Asset

metadata:
  key: nda_base_pdf
  version: 1.0.0
  name: NDA Base Document

spec:
  type: pdf
  file: ./files/nda_form.pdf

Image Asset

apiVersion: signstack/v1beta2
kind: Asset

metadata:
  key: company_logo
  version: 1.0.0
  name: Company Logo

spec:
  type: image
  file: ./images/logo.png

CSS Asset

apiVersion: signstack/v1beta2
kind: Asset

metadata:
  key: corporate_theme
  version: 1.0.0
  name: Corporate Theme

spec:
  type: css
  file: ./styles/corporate.css

HTML Asset with Dependencies

apiVersion: signstack/v1beta2
kind: Asset

metadata:
  key: offer_letter
  version: 1.0.0
  name: Offer Letter
  description: Dynamic offer letter with company branding

spec:
  type: html
  file: ./html/offer_letter.hbs

  partials:
    header: company_header@1.0.0
    footer: legal_footer@1.0.0
    employee_signature:
      asset: signature_block@1.0.0
      roleMap:
        signer: employee

  styles:
    - base_styles@1.0.0
    - corporate_theme@1.0.0

  images:
    logo: company_logo@1.0.0
    watermark: watermark_image@1.0.0

  data:
    schema: offer_letter_context@1.0.0

  pdfSettings:
    paperSize: Letter

HTML Partial

Partials are just HTML assets. They can have their own dependencies:

apiVersion: signstack/v1beta2
kind: Asset

metadata:
  key: company_header
  version: 1.0.0
  name: Company Header

spec:
  type: html
  file: ./files/company_header.html

  styles:
    - header_styles@1.0.0

  images:
    logo: company_logo@1.0.0

  data:
    schema: header_context@1.0.0

How Assets Are Referenced

Templates reference assets via content (the main document) using key@version:

# In a template
spec:
  type: html
  content: offer_letter@1.0.0    # References the HTML asset above

Assets reference other assets in partials, styles, and images using the same key@version format.

Versioning

Assets use semantic versioning. An asset moves from Draft to a concrete published version (1.0.0); to make further changes, you cut a new version (1.1.0, 2.0.0). Published versions are immutable — every template referencing offer_letter_html@1.0.0 keeps rendering the exact content it was designed against, even after 2.0.0 ships.

Draft → 1.0.0 (published, immutable)
          ↓ edit + publish
        1.1.0 (published, immutable)
          ↓ edit + publish
        2.0.0 (published, immutable)

Pick the version bump based on the change:

• MAJOR (2.0.0) — Breaking changes (HBS placeholder removed, viewmodel schema changed)
• MINOR (1.1.0) — Backwards-compatible additions (new optional partial, new image)
• PATCH (1.0.1) — Bug fixes (typo, style tweak)

Best Practices

1. Organize files by type — Keep HTML in ./html/, CSS in ./styles/, images in ./images/, PDFs in ./files/.
2. Make partials reusable — Design partials (headers, footers, signature blocks) to work across multiple templates.
3. Use data schemas on HTML assets — The data.schema field enables validation that your template's data transform produces the shape the HBS expects.

Related Concepts

• Templates — Templates reference assets as their content layer
• Schemas — HTML assets reference schemas for their data context
• File Management — How files are uploaded and stored