AgentSkillsCN

padz-output-customization

提供自定义 padz CLI 输出的指南，涵盖模板与样式表的使用。适用于 padz 渲染工作、调整 pad 显示方式、更改颜色与样式、编辑 Jinja 模板，或与 outstanding crate 集成相关的开发场景。全面覆盖三层样式架构、模板语法，以及编译时嵌入系统。

SKILL.md
--- frontmatter
name: padz-output-customization
description: Guide for customizing padz CLI output using templates and stylesheets. Use when working on padz rendering, modifying how pads are displayed, changing colors/styles, editing Jinja templates, or working with the outstanding crate integration. Covers the three-layer styling architecture, template syntax, and the compile-time embedding system.

Padz Output Customization

Padz uses the outstanding crate for terminal rendering. Output is controlled by:

  1. •Stylesheets (src/styles/default.yaml) - Colors and text decoration
  2. •Templates (src/cli/templates/*.jinja) - Layout and structure

Both are embedded at compile time via outstanding's macros.

Architecture Overview

code
┌─────────────────────────────────────────────────────────────┐
│                     render.rs                                │
│  create_renderer() → Renderer with theme + templates         │
├─────────────────────────────────────────────────────────────┤
│  styles.rs                  │  templates.rs                  │
│  embed_styles!("src/styles")│  embed_templates!("src/cli/   │
│  → DEFAULT_THEME            │  templates") → TEMPLATES       │
├─────────────────────────────────────────────────────────────┤
│  src/styles/default.yaml    │  src/cli/templates/*.jinja     │
└─────────────────────────────────────────────────────────────┘

Stylesheets

Styles use a three-layer architecture:

Layer 1: Visual (prefix _)

Concrete colors - the raw building blocks:

yaml
_primary:
  light: { fg: black }
  dark: { fg: white }

_gold:
  light: { fg: [196, 140, 0] }
  dark: { fg: [255, 214, 10] }

Layer 2: Presentation (prefix _)

Semantic aliases for visual consistency:

yaml
_secondary: _gray
_accent: _gold
_danger: _red

Layer 3: Semantic

Template-facing names - what templates actually use:

yaml
title:
  bold: true
  light: { fg: black }
  dark: { fg: white }

list-index: _accent
error: { bold: true, ... }

Style Properties

yaml
style-name:
  fg: cyan              # Named color
  fg: [255, 128, 0]     # RGB array
  bg: black             # Background
  bold: true
  italic: true
  underline: true
  light: { ... }        # Light mode override
  dark: { ... }         # Dark mode override

Adding a New Style

  1. •Define visual color in Layer 1 (if needed)
  2. •Add presentation alias in Layer 2 (if cross-cutting)
  3. •Define semantic name in Layer 3
  4. •Use in templates: {{ value | style("style-name") }}

Templates

Templates use Jinja2 syntax (minijinja). Located in src/cli/templates/.

Template Files

FilePurpose
list.jinjaMain list view (padz list)
full_pad.jinjaDetailed pad view (padz view)
text_list.jinjaPlain text list output
messages.jinjaSuccess/error messages
_pad_line.jinjaPartial: single pad row
_deleted_help.jinjaPartial: deleted section help
_peek_content.jinjaPartial: content preview
_match_lines.jinjaPartial: search match lines

Template Syntax

jinja
{# Apply style to text #}
{{ pad.title | style("list-title") }}

{# Column layout with fixed width #}
{{ index | style("list-index") | col(4) }}

{# Conditionals #}
{% if pad.is_pinned %}{{ "⚲" | style("pinned") }}{% endif %}

{# Loops #}
{% for pad in pads %}
  {% include "_pad_line.jinja" %}
{% endfor %}

{# Include partials #}
{% include "_deleted_help.jinja" %}

Key Filters

  • •style("name") - Apply named style
  • •col(width) - Fixed column width
  • •col(width, align="right") - Right-aligned column
  • •truncate(length) - Truncate with ellipsis

Creating a New Template

  1. •Create src/cli/templates/mytemplate.jinja
  2. •Access via TEMPLATES.get_content("mytemplate")
  3. •Add to renderer in render.rs

Debugging Output

Use --output=term-debug to see style tags:

bash
padz list --output=term-debug
# Output: [pinned]⚲[/pinned] [list-index]p1.[/list-index]...

Reference

See references/current-stylesheet.yaml for the complete current stylesheet with all styles defined.

Code Locations

ComponentFile
Stylesheetcrates/padz/src/styles/default.yaml
Templatescrates/padz/src/cli/templates/
Style loadingcrates/padz/src/cli/styles.rs
Template loadingcrates/padz/src/cli/templates.rs
Renderer setupcrates/padz/src/cli/render.rs

Common Tasks

Change a color

Edit src/styles/default.yaml, find the style name, modify fg/bg/bold.

Add bold to existing style

yaml
existing-style:
  bold: true
  # ... keep other properties

Change list layout

Edit src/cli/templates/list.jinja and _pad_line.jinja.

Add new output field

  1. •Ensure data is in the render context (check render.rs)
  2. •Add to template: {{ new_field | style("appropriate-style") }}