TRMNL Content Generator
Generate HTML content for TRMNL e-ink display devices.
Prerequisites
Install the trmnl CLI to the latest version:
CODEBLOCK0
Configure a webhook plugin (one-time setup):
CODEBLOCK1
Quick Start Workflow
- 1. Install/update CLI: Run INLINECODE1
- Check plugins: Run
trmnl plugin - if none, prompt user to add one - Confirm device type (default: TRMNL OG, 2-bit, 800x480)
- Read relevant reference docs based on content needs
- Generate HTML using TRMNL framework classes
- Write HTML to a temp file and send:
trmnl send --file /tmp/trmnl-content.html
# Or to a specific plugin:
trmnl send --file /tmp/trmnl-content.html --plugin office
- 7. Minimal confirmation only - Do NOT echo content back to chat
Sending Content
From file (recommended):
CODEBLOCK3
Validate before sending:
CODEBLOCK4
View send history:
CODEBLOCK5
Webhook Limits
| Tier | Payload Size | Rate Limit |
|---|
| Free | 2 KB (2,048 bytes) | 12 requests/hour |
| TRMNL+ |
5 KB (5,120 bytes) | 30 requests/hour |
Set tier globally for accurate validation:
CODEBLOCK6
Reference Documentation
Read these files as needed:
| File | When to Read |
|---|
| INLINECODE3 | Start here - Common plugin patterns |
| INLINECODE4 |
Device specs, e-ink constraints |
|
references/css-utilities.md | Colors, typography, sizing, spacing |
|
references/layout-systems.md | Flexbox, grid, overflow engines |
|
references/components.md | Title bar, dividers, items, tables |
|
references/webhook-api.md | Payload format, troubleshooting |
|
assets/anti-patterns.md | Common mistakes to avoid |
Standard Plugin Structure
Every plugin follows this pattern:
CODEBLOCK7
- -
layout + layout--col = vertical flex container - INLINECODE12 = push sections to edges
- INLINECODE13 = always at bottom, outside layout
- INLINECODE14 = separate major sections
- CRITICAL: Only ONE
.layout element per view
Quick Reference
Grid System (10-Column)
CODEBLOCK8
Item Component
CODEBLOCK9
Value Typography
Always use value--tnums for numbers.
| Class | Usage |
|---|
| INLINECODE17 | Hero KPIs |
| INLINECODE18 |
Large prices |
|
value--xlarge | Secondary metrics |
|
value--tnums |
Required for numbers |
Grayscale Classes
Use dithered classes, not inline colors:
- -
bg--black, bg--gray-60, bg--gray-30, bg--gray-10, INLINECODE25 - INLINECODE26 , INLINECODE27
Data Attributes
| Attribute | Purpose |
|---|
| INLINECODE28 | Auto-resize text to fit |
| INLINECODE29 |
Limit to N lines |
|
data-overflow="true" | Enable overflow management |
Best Practices
- 1. Use
layout + title_bar structure - Always
value--tnums for numbers - Use
data-fit-value on primary metrics - Use
bg--gray-* dithered classes - Keep payload under tier limit
- Minimal confirmations - just "Sent to TRMNL"
Troubleshooting
| Problem | Solution |
|---|
| INLINECODE36 | Run INLINECODE37 |
| No plugins configured |
Run
trmnl plugin add <name> <url> |
| Webhook fails |
trmnl config - verify plugin URL |
| Payload too large |
trmnl validate --file - check size |
| Numbers misaligned | Add
value--tnums class |
| Send history |
trmnl history --failed |
TRMNL 内容生成器
为TRMNL电子墨水屏显示设备生成HTML内容。
前置条件
将trmnl CLI更新至最新版本：
bash
npm install -g trmnl-cli@latest
配置Webhook插件（一次性设置）：
bash
添加插件
trmnl plugin add home https://trmnl.com/api/custom_plugins/{uuid}
验证配置
trmnl plugin
快速入门工作流程
- 1. 安装/更新CLI： 运行 npm install -g trmnl-cli@latest
- 检查插件： 运行 trmnl plugin - 若无插件，提示用户添加一个
- 确认设备类型（默认：TRMNL OG，2位色，800x480）
- 根据内容需求阅读相关参考文档
- 使用TRMNL框架类生成HTML
- 将HTML写入临时文件并发送：
bash
trmnl send --file /tmp/trmnl-content.html
# 或发送至特定插件：
trmnl send --file /tmp/trmnl-content.html --plugin office
- 7. 仅做最小化确认 - 不要在聊天中回显内容
发送内容
从文件发送（推荐）：
bash
先将HTML内容写入文件
cat > /tmp/trmnl-content.html << EOF
我的插件
EOF
发送至显示屏
trmnl send --file /tmp/trmnl-content.html
发送前验证：
bash
trmnl validate --file /tmp/trmnl-content.html
查看发送历史：
bash
trmnl history
trmnl history --today
trmnl history --failed
Webhook限制
| 层级 | 负载大小 | 速率限制 |
|---|
| 免费版 | 2 KB（2,048字节） | 12次请求/小时 |
| TRMNL+ |
5 KB（5,120字节） | 30次请求/小时 |
全局设置层级以确保准确验证：
bash
trmnl tier plus # 或 free
参考文档
根据需要阅读以下文件：
| 文件 | 何时阅读 |
|---|
| references/patterns.md | 从这里开始 - 常见插件模式 |
| references/framework-overview.md |
设备规格、电子墨水屏限制 |
| references/css-utilities.md | 颜色、排版、尺寸、间距 |
| references/layout-systems.md | Flexbox、网格、溢出引擎 |
| references/components.md | 标题栏、分隔线、项目、表格 |
| references/webhook-api.md | 负载格式、故障排除 |
| assets/anti-patterns.md | 需避免的常见错误 |
标准插件结构
每个插件遵循此模式：
html
插件名称
上下文
- - layout + layout--col = 垂直弹性容器
- gap--space-between = 将区块推至边缘
- title_bar = 始终位于底部，在布局外部
- divider = 分隔主要区域
- 关键： 每个视图仅一个 .layout 元素
快速参考
网格系统（10列）
html
项目组件
html
数值排版
数字始终使用 value--tnums。
| 类名 | 用途 |
|---|
| value--xxxlarge | 核心KPI |
| value--xxlarge |
大额价格 |
| value--xlarge | 次要指标 |
| value--tnums |
数字必用 |
灰度类
使用抖动类，而非内联颜色：
- - bg--black、bg--gray-60、bg--gray-30、bg--gray-10、bg--white
- text--black、text--gray-50
数据属性
| 属性 | 用途 |
|---|
| data-fit-value=true | 自动调整文字大小 |
| data-clamp=N |
限制为N行 |
| data-overflow=true | 启用溢出管理 |
最佳实践
- 1. 使用 layout + title_bar 结构
- 数字始终使用 value--tnums
- 主要指标使用 data-fit-value
- 使用 bg--gray-* 抖动类
- 保持负载在层级限制内
- 最小化确认 - 仅回复已发送至TRMNL
故障排除
| 问题 | 解决方案 |
|---|
| trmnl: command not found | 运行 npm install -g trmnl-cli@latest |
| 未配置插件 |
运行 trmnl plugin add <名称> <网址> |
| Webhook失败 | trmnl config - 验证插件URL |
| 负载过大 | trmnl validate --file - 检查大小 |
| 数字未对齐 | 添加 value--tnums 类 |
| 发送历史 | trmnl history --failed |
