# HTML Template Specification

Technical specification for the TiddlyWiki-style HTML output.

## Overview

The output is a single, self-contained HTML file with:
- All CSS embedded inline
- All JavaScript embedded inline
- All images embedded as Base64
- Full offline functionality

## File Structure

```html
<!DOCTYPE html>
<html lang="zh-CN">
<head>
  <meta charset="UTF-8">
  <meta name="viewport" content="width=device-width, initial-scale=1.0">
  <title>{{SOFTWARE_NAME}} - User Manual</title>
  <style>{{EMBEDDED_CSS}}</style>
</head>
<body class="wiki-container" data-theme="light">
  <aside class="wiki-sidebar">...</aside>
  <main class="wiki-content">...</main>
  <button class="theme-toggle">...</button>
  <script id="search-index" type="application/json">{{SEARCH_INDEX}}</script>
  <script>{{EMBEDDED_JS}}</script>
</body>
</html>
```

## Placeholders

| Placeholder | Description | Source |
|-------------|-------------|--------|
| `{{SOFTWARE_NAME}}` | Software name | manual-config.json |
| `{{VERSION}}` | Version number | manual-config.json |
| `{{EMBEDDED_CSS}}` | All CSS content | wiki-base.css + wiki-dark.css |
| `{{TOC_HTML}}` | Table of contents | Generated from sections |
| `{{TIDDLERS_HTML}}` | All content blocks | Converted from Markdown |
| `{{SEARCH_INDEX_JSON}}` | Search data | Generated from content |
| `{{EMBEDDED_JS}}` | JavaScript code | Inline in template |
| `{{TIMESTAMP}}` | Generation timestamp | ISO 8601 format |
| `{{LOGO_BASE64}}` | Logo image | Project logo or generated |

## Component Specifications

### Sidebar (`.wiki-sidebar`)

```
Width: 280px (fixed)
Position: Fixed left
Height: 100vh
Components:
  - Logo area (.wiki-logo)
  - Search box (.wiki-search)
  - Tag navigation (.wiki-tags)
  - Table of contents (.wiki-toc)
```

### Main Content (`.wiki-content`)

```
Margin-left: 280px (sidebar width)
Max-width: 900px (content)
Components:
  - Header bar (.content-header)
  - Tiddler container (.tiddler-container)
  - Footer (.wiki-footer)
```

### Tiddler (Content Block)

```html
<article class="tiddler"
         id="tiddler-{{ID}}"
         data-tags="{{TAGS}}"
         data-difficulty="{{DIFFICULTY}}">
  <header class="tiddler-header">
    <h2 class="tiddler-title">
      <button class="collapse-toggle">▼</button>
      {{TITLE}}
    </h2>
    <div class="tiddler-meta">
      <span class="difficulty-badge {{DIFFICULTY}}">{{DIFFICULTY_LABEL}}</span>
      {{TAG_BADGES}}
    </div>
  </header>
  <div class="tiddler-content">
    {{CONTENT_HTML}}
  </div>
</article>
```

### Search Index Format

```json
{
  "tiddler-overview": {
    "title": "Product Overview",
    "body": "Plain text content for searching...",
    "tags": ["getting-started", "overview"]
  },
  "tiddler-ui-guide": {
    "title": "UI Guide",
    "body": "Plain text content...",
    "tags": ["ui-guide"]
  }
}
```

## Interactive Features

### 1. Search

- Full-text search with result highlighting
- Searches title, body, and tags
- Shows up to 10 results
- Keyboard accessible (Enter to search, Esc to close)

### 2. Collapse/Expand

- Per-section toggle via button
- Expand All / Collapse All buttons
- State indicated by ▼ (expanded) or ▶ (collapsed)
- Smooth transition animation

### 3. Tag Filtering

- Tags: all, getting-started, ui-guide, api, config, troubleshooting, examples
- Single selection (radio behavior)
- "all" shows everything
- Hidden tiddlers via `display: none`

### 4. Theme Toggle

- Light/Dark mode switch
- Persists to localStorage (`wiki-theme`)
- Applies to entire document via `[data-theme="dark"]`
- Toggle button shows sun/moon icon

### 5. Responsive Design

```
Breakpoints:
  - Desktop (> 1024px): Sidebar visible
  - Tablet (768-1024px): Sidebar collapsible
  - Mobile (< 768px): Sidebar hidden, hamburger menu
```

### 6. Print Support

- Hides sidebar, toggles, interactive elements
- Expands all collapsed sections
- Adjusts colors for print
- Page breaks between sections

## Accessibility

### Keyboard Navigation

- Tab through interactive elements
- Enter to activate buttons
- Escape to close search results
- Arrow keys in search results

### ARIA Attributes

```html
<input aria-label="Search">
<nav aria-label="Table of Contents">
<button aria-label="Toggle theme">
<div aria-live="polite"> <!-- For search results -->
```

### Color Contrast

- Text/background ratio ≥ 4.5:1
- Interactive elements clearly visible
- Focus indicators visible

## Performance

### Target Metrics

| Metric | Target |
|--------|--------|
| Total file size | < 10MB |
| Time to interactive | < 2s |
| Search latency | < 100ms |

### Optimization Strategies

1. **Lazy loading for images**: `loading="lazy"`
2. **Efficient search**: In-memory index, no external requests
3. **CSS containment**: Scope styles to components
4. **Minimal JavaScript**: Vanilla JS, no libraries

## CSS Variables

### Light Theme

```css
:root {
  --bg-primary: #ffffff;
  --bg-secondary: #f8f9fa;
  --text-primary: #212529;
  --text-secondary: #495057;
  --accent-color: #0d6efd;
  --border-color: #dee2e6;
}
```

### Dark Theme

```css
[data-theme="dark"] {
  --bg-primary: #1a1a2e;
  --bg-secondary: #16213e;
  --text-primary: #eaeaea;
  --text-secondary: #b8b8b8;
  --accent-color: #4dabf7;
  --border-color: #2d3748;
}
```

## Markdown to HTML Mapping

| Markdown | HTML |
|----------|------|
| `# Heading` | `<h1>` |
| `## Heading` | `<h2>` |
| `**bold**` | `<strong>` |
| `*italic*` | `<em>` |
| `` `code` `` | `<code>` |
| `[link](url)` | `<a href="url">` |
| `- item` | `<ul><li>` |
| `1. item` | `<ol><li>` |
| ``` ```js ``` | `<pre><code class="language-js">` |
| `> quote` | `<blockquote>` |
| `---` | `<hr>` |

## Screenshot Embedding

### Marker Format

```markdown
<!-- SCREENSHOT: id="ss-login" url="/login" description="Login form" -->
```

### Embedded Format

```html
<figure class="screenshot">
  <img src="data:image/png;base64,{{BASE64_DATA}}"
       alt="Login form"
       loading="lazy">
  <figcaption>Login form</figcaption>
</figure>
```

### Placeholder (if missing)

```html
<div class="screenshot-placeholder">
  [Screenshot: ss-login - Login form]
</div>
```

## File Size Optimization

### CSS

- Minify before embedding
- Remove unused styles
- Combine duplicate rules

### JavaScript

- Minify before embedding
- Remove console.log statements
- Use IIFE for scoping

### Images

- Compress before Base64 encoding
- Use appropriate dimensions (max 1280px width)
- Consider WebP format if browser support is acceptable

## Validation

### HTML Validation

- W3C HTML5 compliance
- Proper nesting
- Required attributes present

### CSS Validation

- Valid property values
- No deprecated properties
- Vendor prefixes where needed

### JavaScript

- No syntax errors
- All functions defined
- Error handling for edge cases

## Testing Checklist

- [ ] Opens in Chrome/Firefox/Safari/Edge
- [ ] Search works correctly
- [ ] Collapse/expand works
- [ ] Tag filtering works
- [ ] Theme toggle works
- [ ] Print preview correct
- [ ] Keyboard navigation works
- [ ] Mobile responsive
- [ ] Offline functionality
- [ ] All links valid
- [ ] All images display
- [ ] No console errors
