# Template Creation Prompt for AI

This document describes the data structures, helper functions, and conventions an AI needs to create or modify HTML templates for this social media archive system.

## Data Structures Available

### Post Data (when rendering posts)
- **Available in all post templates (card, list, detail):**
  - platform: string (e.g., "reddit", "hackernews")
  - id: string (unique post identifier)
  - title: string
  - author: string
  - timestamp: integer (unix timestamp)
  - score: integer (up/down vote score)
  - replies: integer (number of comments)
  - url: string (original post URL)
  - content: string (optional post body text)
  - source: string (optional subreddit/community)
  - tags: array of strings (optional tags/flair)
  - meta: object (optional platform-specific metadata)
  - comments: array (optional nested comment tree - only in detail templates)
  - post_url: string (generated: "{uuid}.html" - for local linking to detail pages)

### Comment Data (when rendering comments)
- **Available in comment templates:**
  - uuid: string (unique comment identifier)
  - id: string (platform-specific identifier)
  - author: string (comment author username)
  - content: string (comment text)
  - timestamp: integer (unix timestamp)
  - score: integer (comment score)
  - platform: string
  - depth: integer (nesting level)
  - children: array (nested replies)
  - children_section: string (pre-rendered HTML of nested children)

## Template Engine: Jinja2

Templates use Jinja2 syntax (`{{ }}` for variables, `{% %}` for control flow).

### Important Filters:
- `|safe`: Mark content as safe HTML (for already-escaped content)
- Example: `{{ renderMarkdown(content)|safe }}`

### Available Control Structures:
- `{% if variable %}...{% endif %}`
- `{% for item in array %}...{% endfor %}`
- `{% set variable = value %}` (create local variables)

## Helper Functions Available

Call these in templates using `{{ function(arg) }}`:

### Time/Date Formatting:
- `formatTime(timestamp)` -> "HH:MM"
- `formatTimeAgo(timestamp)` -> "2 hours ago"
- `formatDateTime(timestamp)` -> "January 15, 2024 at 14:30"

### Text Processing:
- `truncate(text, max_length)` -> truncated string with "..."
- `escapeHtml(text)` -> HTML-escaped version

### Content Rendering:
- `renderMarkdown(text)` -> Basic HTML from markdown (returns already-escaped HTML)

## Template Types

### Card Template (for index/listing pages)
- Used for summary view of posts
- Links should use `post_url` to point to local detail pages
- Keep concise - truncated content, basic info

### List Template (compact listing)
- Even more compact than cards
- Vote scores, basic metadata, title link

### Detail Template (full post view)
- Full content, meta information
- Source link uses `url` (external)
- Must include `{{comments_section|safe}}` for rendered comments

### Comment Template (nested comments)
- Recursive rendering with depth styling
- Children rendered as flattened HTML in `children_section`

## Convenience Data Added by System

In `generate_html.py`, `post_url` is added to each post before rendering: `{post['uuid']}.html`

This allows templates to link to local detail pages instead of external Reddit.

## CSS Classes Convention

Templates use semantic CSS classes:
- Post cards: `.post-card`, `.post-header`, `.post-meta`, etc.
- Comments: `.comment`, `.comment-header`, `.comment-body`, etc.
- Platform: `.platform-{platform}` for platform-specific styling

## Examples

### Conditional Rendering:
```
{% if content %}
  <p class="content">{{ renderMarkdown(content)|safe }}</p>
{% endif %}
```

### Looping Tags:
```
{% for tag in tags if tag %}
  <span class="tag">{{ tag }}</span>
{% endfor %}
```

### Styling by Depth (comments):
```
<div class="comment" style="margin-left: {{depth * 20}}px">
```

When creating new templates, follow these patterns and use the available data and helper functions appropriately.