Imported from doekenorg/trmnl-bijbeltekst-vd-dag (AGENTS.md). Install upstream with npx skills add doekenorg/trmnl-bijbeltekst-vd-dag. Copyright stays with the author.

Bijbelvers van de dag — TRMNL Plugin

Project

This is the TRMNL plugin "Bijbelvers van de dag" (settings.yml id 333323). It shows the daily Dutch Bible verse on an e-ink TRMNL device: the feed title, the verse reference, and the verse text. Data comes from polling the Dagelijks Woord RSS feed https://feed.dagelijkswoord.nl/rss2/bgt on a 240-minute refresh. It is built against TRMNL framework v3.1.

The one user setting is date_position (none / verse / title_bar), which decides where the date of the verse shows up. title_bar uses the written-out date on full and half horizontal, and the numeric dd/mm/yyyy on half vertical and quadrant, because their bar is half as wide.

Layout / Structure

The repo root contains this AGENTS.md, a CLAUDE.md (which imports it), and a src/ folder.

src/ — the live plugin

These files are pasted into or synced with TRMNL.

• src/settings.yml — plugin config: polling, refresh, framework_version, and custom_fields (the user-facing config form).
• src/shared.liquid — prepended to EVERY view before render. It holds the feed assigns (feed_title, verse_reference, verse_text), the date assigns (verse_date, titlebar_date, titlebar_date_short — each empty unless date_position selects it), the plugin constants (plugin_title, icon_url), and all reusable partials defined via {% template name %}…{% endtemplate %}.
• src/transform.js — serverless transform, run on the polled feed before render. It strips the Bible reference the feed repeats at the end of each verse, and splits the dated title into reference, date and date_short. Define function run(input) and return JSON-serialisable data; serverless_language: node in settings.yml selects the runtime, and the same code runs in production. Set transform_runtime: disabled in .trmnlp.yml to bypass it locally.
• src/full.liquid, src/half_horizontal.liquid, src/half_vertical.liquid, src/quadrant.liquid — the four device layouts. Each is just layout markup plus {% render %} calls. Keep them thin.

Partials

Partials live in src/shared.liquid:

• verse_block(heading, reference, date, body, reference_class, date_class, body_class, width_class, body_style) — the centred verse column. The four *_class params tune type size and column width per layout; each has a default, so never pass an empty string. date is the optional grey line under the reference, dropped when blank. body_style is the line-height escape hatch (see rule 1) and is omitted entirely when blank.
• titlebar(title, icon, date) — the bottom title bar. date renders as the framework's .instance span (right-aligned, ellipsised) and is dropped when blank.

{% render %} is scope-isolated: a partial ONLY sees the params you pass it, not the shared assigns. Pass every variable a partial needs.

Layout differences

The four views render the same content at different densities:

The date under the reference sits one notch below it on the font scale: base → lg: large on full and half horizontal, small → lg: base (the partial default) on the two small views.

All four show the reference. Every text steps up exactly one notch on the font scale (small → base → large → xlarge) at lg:, so TRMNL X gains size without changing the relative hierarchy. The heading and both partial defaults carry their own lg: step, so a view that passes no *_class still scales.

The narrow layouts widen the column because cqw is a percentage of the CONTAINER, not the screen: 60cqw of a quadrant is a ~4-word line.

Best Practices (HARD RULES)

1. Utility classes only. NO inline style="". TRMNL discourages inline styles. Use the native equivalents: width/height w--{n} / h--{n}, w--full / h--full, arbitrary w--[Npx], and percentage-of-.layout via container-query units w--[Ncqw] / h--[Ncqh] (N from 0–100). Centre with flex--center-x / flex--center-y, not margin:0 auto. Hide/show with hidden (display:none) / visible (display:block).

   One sanctioned exception: line-height. The framework ships no line-height utility — font--* sets family, size and leading together, so leading cannot be tuned without overriding the size too. verse_block therefore takes a body_style param, used by full.liquid and both halves to set the verse leading to 1.4. Quadrant is left at the framework default — its font--small body is already tight on space. Do not widen this exception to properties that DO have a utility, and do not "fix" the existing uses by deleting them.

2. Device / responsive states. Prefixes: size sm: (≥600), md: (≥800), lg: (≥1024); orientation portrait: (landscape is the unprefixed default — portrait is the odd one out); bit-depth 1bit: / 2bit: / 4bit:; and dark:. Mapping: base = the original/OG TRMNL (smaller screen) in landscape, lg: = TRMNL X (the larger 4-bit screen), and portrait: = a device mounted portrait. Combine in the order dark:size:orientation:bit-depth:utility (e.g. md:portrait:4bit:gap--large). Never use landscape:-prefixed classes, even though the shipped framework CSS contains them and the official docs mention them — this rule is correct and the docs are not. The runtime never sets a screen--landscape class, so landscape: padding/margin utilities are dead, while the landscape: flex rules match via :not(.screen--portrait) and therefore leak into lg: landscape with tie-breaking specificity that lg:landscape: overrides cannot reliably win. To target OG-landscape only: style the base, then undo with portrait: and lg:. When verifying that a prefixed class exists in the framework CSS, beware that most rules live in comma-grouped selector lists — grep for the bare class name (e.g. portrait\\:px--2), not for a { right after it.

3. Arbitrary utilities ARE prefixable. The framework pre-generates sm:, md:, lg: and portrait: variants of the arbitrary bracket utilities (w--max-[Ncqw] for every N from 0–100, and so on), so portrait:w--max-[100cqw] is real and wins over the unprefixed base. Verify with a grep for the bare escaped class name (portrait\\:w--max-\\[100cqw\\]) — and mind the shell: over-escaping in a double-quoted grep pattern silently returns zero hits and makes a class that exists look missing.

4. Specificity gotcha. More modifiers means higher specificity. A prefixed display utility like lg:flex carries a default ~10px gap that OUTRANKS an unprefixed gap--xlarge. When you set display with a prefix, set the gap at the same prefix level (lg:gap--xlarge).

5. Equal sizing. Equal WIDTH → grid columns (grid--cols-N, 1fr each, content-independent). Equal HEIGHT → flex grow rows plus cards with h--full. grow alone gives content-width, NOT equal width.

6. RSS shape. The feed is parsed into rss.channel. The verse of the day is rss.channel.item[0] — .title is the date plus the Bible reference, .description is the verse text. Read the feed through the shared.liquid assigns rather than repeating the rss.channel.item[0] path in every view. .description arrives with the reference appended after a -- separator; transform.js removes it, so the views must NOT strip it again. transform.js also adds .reference, .date and .date_short. Verse text length varies a lot between days; check long verses when changing type sizes.

   The date to show is the one in .title, never .pubDate: the feed publishes the next day's verse the evening before, so pubDate is a day behind the date the verse is for.

7. The transform runs at poll time, not render time. Its output is cached with the polled payload, so a pushed transform.js change does nothing until the next poll — up to refresh_interval (240 minutes) later. Until then the live plugin renders the OLD payload against the NEW templates, which looks like a template bug: fields the transform adds (item.reference) come out empty and fields it strips (the -- tail on .description) are still there. Force a refresh on trmnl.com after pushing a transform change instead of debugging the Liquid. Local trmnlp re-polls on demand, which is why dev looks correct while production does not.

8. Config in Liquid. Read trmnl.plugin_settings.custom_fields_values. Boolean fields arrive as the STRINGS "true" / "false" — normalize them before {% if %}. Numeric select values: coerce with | plus: 0 before a where match. Provide defaults with | default:.

   Liquid counts only nil and false as falsy, so an EMPTY STRING is truthy: {% if date %} fires on '' and renders an empty element. Guard optional partial params with {% if x != blank %}, which covers nil, '' and an unpassed param in one go.

9. settings.yml / form-builder schema. Use only the documented top-level keys (name, strategy, polling_*, refresh_interval, framework_version, dark_mode, no_screen_padding, custom_fields, id). Field types: select, string, number, code (a textarea — use rows:), date, boolean, author_bio. There is NO text type. author_bio is itself a FIELD (it renders an About card), not a top-level key. select options are - Label: value at the same indent as options:.

10. Per-template ~100 KB limit. Anything bulky and shared belongs ONCE in shared.liquid (which is prepended to all views) rather than duplicated per view. Keep the view files thin.

11. The title bar icon is a remote URL. It is hot-linked from uxwing.com, so it breaks if that host goes away. Replacing it with an inlined SVG sprite in shared.liquid is the durable fix.

12. When given a documentation link, read it (verbatim if needed) — do not guess a schema or API.

Workflow Note

TRMNL's local dev tool (trmnlp) and the import/export ZIP expect the plugin files in a src/ folder, which this repo uses. Preview locally with bin/trmnlp serve; .trmnlp.yml sets the watch paths and the Europe/Amsterdam time zone.