Skip to content

Styles and brands

The same Document renders in two looks. You choose the look when you render, never when you build.

StyleUse it for
classic (default)existing AlgoReports emails; byte-identical to 0.1.4–0.1.6
modernnew reports and alerts: a masthead, KPI tiles, tagged tables and restyled charts
from common_reports import EmailRenderer, InteractiveHtmlRenderer
email = doc.render(EmailRenderer(style="modern", preheader="NAV +0.42% today"))
page = doc.render(InteractiveHtmlRenderer(style="modern", date="30 Sep 2026"))
page.save("reports/2026-09-30.html")

Modern email options

ArgumentDefaultMeaning
brandNULL_CAPITALwho the report is from; Brand() for unbranded
preheaderfrontmatter preheaderthe preview line shown after the subject
title, datefrontmatteroverride the masthead
images"cid""cid" sends images as inline parts, which must travel in .attachments; "data-uri" embeds them in the HTML

With images="cid", always pass attachments=email.attachments to send(). Without them, the crest and charts show as broken images.

Brand

from common_reports.contracts.builders import NULL_CAPITAL, Brand
EmailRenderer(style="modern") # Null Capital
EmailRenderer(style="modern", brand=Brand()) # neutral, no crest or wordmark
EmailRenderer(
style="modern",
brand=Brand( # any other house
name="Acme Partners",
logo=Path("acme.png"),
accent="#0b6e4f",
footer="Acme Partners LLC",
),
)
FieldMeaning
name, tagline, url, footerthe wordmark, the line under it, the link, the closing line
logo, logo_darkPNG bytes or a path; the dark one is used where mail apps support dark mode
ink, paper, muted, hair, accent, canvasthe light palette
positive, negative, warningthe tone colours
dark_*the same palette for dark mode
font, monofont stacks; use single quotes inside them
serieschart colours, in order
chart_card, chart_text, chart_markcharts on a card or see-through, their text tone, the crest in the corner

NULL_CAPITAL is the neutral palette with the Null Capital crest (light and dark versions ship with the package), see-through charts and the chart crest.

Dark mode

The modern email follows the reader’s mail app:

  • Apple Mail and iOS Mail: the dark palette applies (prefers-color-scheme).
  • Gmail and Outlook apps: they apply their own colour inversion to the light version.
  • Charts: see-through charts sit on either background unchanged.

There is no forced-dark mode. Gmail on phones inverts a dark email back to light grey, so the look would differ by device.

Notes and disclaimers

b.disclaimer(text) adds small print at the very end of the modern email, under the sign-off line (brand name and date). Several calls give several notes, in order, so numbered footnotes (“1. …”, “2. …”) work the way a factsheet’s do. Table titles (table(..., caption=...)) are drawn at 15px.

The attachment note

When an email is sent with file attachments (for example an interactive .html report), a modern email shows a styled “Interactive report attached” box. With no file attachments, the box is removed. Inline images do not count as files.

  • Wording: set EMAIL_ATTACHMENT_NOTE or the context’s attachment_note.
  • Turning it off: set it to none.

Classic emails keep the plain AlgoReports trailer.

Size

Gmail hides message HTML past about 102 KB behind a “View entire message” link. Check email.manifest["gmail_clip_risk"] before sending a long report. Keep images as cid parts, and move long tables into the attached interactive page.

Interactive page

InteractiveHtmlRenderer(style="modern") writes one standalone file:

  • the brand masthead and a table of contents built from the sections;
  • live Plotly charts, each with a static image under it for readers without script;
  • all images inside the file.
ArgumentDefaultMeaning
plotly"cdn""cdn" loads Plotly from its CDN (small file); "inline" embeds it (works offline, about 4 MB larger)
brand, title, dateas the email

GhostRenderer publishes the classic page to Ghost. It has no modern style and raises ValueError if you ask for one.