Styles and brands
The same Document renders in two looks. You choose the look when you render, never
when you build.
| Style | Use it for |
|---|---|
classic (default) | existing AlgoReports emails; byte-identical to 0.1.4–0.1.6 |
modern | new 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
| Argument | Default | Meaning |
|---|---|---|
brand | NULL_CAPITAL | who the report is from; Brand() for unbranded |
preheader | frontmatter preheader | the preview line shown after the subject |
title, date | frontmatter | override 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 CapitalEmailRenderer(style="modern", brand=Brand()) # neutral, no crest or wordmarkEmailRenderer( style="modern", brand=Brand( # any other house name="Acme Partners", logo=Path("acme.png"), accent="#0b6e4f", footer="Acme Partners LLC", ),)| Field | Meaning |
|---|---|
name, tagline, url, footer | the wordmark, the line under it, the link, the closing line |
logo, logo_dark | PNG bytes or a path; the dark one is used where mail apps support dark mode |
ink, paper, muted, hair, accent, canvas | the light palette |
positive, negative, warning | the tone colours |
dark_* | the same palette for dark mode |
font, mono | font stacks; use single quotes inside them |
series | chart colours, in order |
chart_card, chart_text, chart_mark | charts 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_NOTEor the context’sattachment_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.
| Argument | Default | Meaning |
|---|---|---|
plotly | "cdn" | "cdn" loads Plotly from its CDN (small file); "inline" embeds it (works offline, about 4 MB larger) |
brand, title, date | as the email |
GhostRenderer publishes the classic page to Ghost. It has no modern style and raises
ValueError if you ask for one.