Skip to main content

What is Ceres?

Ceres is a document renderer. It takes data from an API (like an invoice or a quotation) and turns it into a good-looking HTML document using a template you write.

Think of it like a mail merge. You have a template with placeholders, and Ceres fills in the blanks with real data.

Where does Ceres fit in?​

Refrens has two ways to render documents:

  1. System templates live inside Lydia (the main React app). These are built-in and handle most users.
  2. Custom templates live inside Ceres. When a user wants a custom look (different layout, colors, fonts), Ceres takes over.

Here is how it works:

User opens a document in Lydia
        |
        v
Does this user have a custom template?
        |
   No --+-- Yes
   |         |
   v         v
Lydia       Lydia loads Ceres
renders     inside an iframe
it with     and passes it the
a React     document data URL
template

Lydia and Ceres talk to each other through postMessage. Ceres tells Lydia how tall the content is. Lydia tells Ceres when to print.

What is a template?​

A template is a folder with a few files:

src/templates/my-cool-invoice/
  index.ts          # Wires everything together
  template.hbs      # The HTML layout (Handlebars)
  styles.css        # The look and feel
  version.json      # Auto-managed version number
  samples.json      # Test URLs for previewing

You write the HTML in Handlebars (a templating language that lets you put {{variableName}} in your HTML). You style it with plain CSS. That is it.

What are widgets?​

Widgets are reusable bits of HTML that you can drop into any template. For example:

  • InvoiceStatus shows a colored tag like "Paid" (green) or "Overdue" (red)
  • DateTime formats dates with timezone support
  • MarkdownViewer renders markdown text as HTML
  • DemoBadge shows a "Demo" watermark

You use them in your template like this:

{{> InvoiceStatus}}
{{> DemoBadge}}
{{> MarkdownViewer (prepareMarkdownViewerData notes)}}

The {{> WidgetName}} syntax is called a partial. A partial is just a reusable chunk of HTML that you can drop into any template.

Next steps​