mirror of
https://github.com/catlog22/Claude-Code-Workflow.git
synced 2026-02-12 02:37:45 +08:00
7aa1cda367
- Implemented main render function for the issue discovery view. - Added data loading functions to fetch discoveries, details, findings, and progress. - Created rendering functions for discovery list and detail sections. - Introduced filtering and searching capabilities for findings. - Implemented actions for exporting and dismissing findings. - Added polling mechanism to track discovery progress. - Included utility functions for HTML escaping and cleanup.
326 lines
7.0 KiB
Markdown
326 lines
7.0 KiB
Markdown
# 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
|