tech-article-craft

# Tech Article Craft Produces a **single self-contained, standalone HTML file** for a publication-ready technical article. Each article is fully independent — no cross-article navigation, no shared CSS/JS, no external dependencies beyond CDNs. The output is ready to publish anywhere: a static host, a folder, an email attachment, or a single file share. **Core principle**: One HTML file + one images folder. Move the folder, the article works. No site scaffolding required. ## When to Invoke - User asks to "write an article" / "写一篇文章" about a technical topic - User provides a draft/outline and asks to expand it into a full article - User provides a source document and asks to "整理成技术文章" - User asks to create a standalone, shareable, self-contained article ## Output Artifacts | Artifact | Location | Naming | |----------|----------|--------| | Article HTML | `{output-dir}/{slug}/index.html` | Always `index.html` inside a slug folder | | Hero image | `{output-dir}/{slug}/images/hero.jpg` | landscape_16_9, no hex codes in prompt | | Inline images | `{output-dir}/{slug}/images/{section}.jpg` | landscape_4_3, natural language colors | | SVG diagrams | Inline in HTML (preferred) or `images/{section}.svg` | Embedded when small | **Why a folder instead of a flat file**: images stay as separate files to preserve full quality. The whole `{slug}/` folder is the unit of distribution — zip it, upload it, or host it as-is. The `index.html` inside references images via relative `images/xxx.jpg` paths, so it works without a server (open via `file://`). If the user explicitly wants a **truly single file** (no images folder), convert images to base64 data URIs at the end (see Step 7). ## Full Workflow (7 Steps) ### Step 1: Research & Plan 1. If user provided a source document, read it fully (use offset/limit for >64KB files) 2. WebSearch for latest information on the topic (timely data, 2-5 queries) 3. WebFetch authoritative sources for full content 4. Plan article structure: 6-8 chapters, each with clear theme 5. Identify 3-4 points where inline images or diagrams would aid understanding 6. Decide a `{slug}` — short, kebab-case, English, derived from the topic (e.g. `physical-ai`, `ai-side-hustle`) ### Step 2: Generate Hero Image Use GenerateImage tool with these rules: - **Format**: `[PURPOSE]: [DETAILED DESCRIPTION]` - **Size**: `landscape_16_9` (1280x720) - **Path**: `{output-dir}/{slug}/images/hero` - **CRITICAL**: Never use hex color codes (`#00f0ff`) in prompts — the image generator will render them as text labels. Use natural language: "cyan-blue", "deep black", "neon accent" - **Style**: Dark cinematic, neural network / tech elements, no text/words/labels/watermarks/logos/UI-borders (see "Mandatory Prohibitions" below) - If first generation has artifacts, regenerate with "(1)" suffix, then delete original and rename ### Step 3: Generate Inline Images For each section that benefits from visualization: - **Size**: `landscape_4_3` (1152x864) - **Path**: `{output-dir}/{slug}/images/{section-name}` - Same no-hex-code rule as hero image - Same mandatory prohibitions (no logos, watermarks, UI borders, extraneous English) — see "Mandatory Prohibitions" in Image Generation Rules - Each image should illustrate a specific concept, not be decorative ### Step 4: Generate Technical Diagrams **Prefer pure HTML/CSS components** over SVG — they're responsive, editable, and match the article theme. Use SVG only for complex topologies, sequence diagrams, or network layouts. Never use Mermaid (rendering issues with Chinese text). Available HTML/CSS components (all CSS is inlined in the article's `<style>`, definitions provided in the template below): - `.arch-layer-stack` — layered architecture diagram - `.skill-cards` / `.skill-card` — card grid layout - `.hitl-flow` / `.hitl-stage` — process flow with arrows - `.dataflow-pipeline` — data pipeline visualization - `.impl-phases` — implementation phases grid - `.cost-table` — comparison tables - `.event-topics` — event-driven architecture grid - `.pain-points` / `.pain-card` — problem analysis grid - `.match-layers` — multi-layer matching engine - `.router-flow` / `.router-node` — routing flow diagram - `.skill-tiers` — tiered architecture - `.compare-table` — feature comparison table with highlight - `.code-block` — code/config examples with syntax highlighting - `.callout` — highlighted info/warning box If SVG is needed: 1. Classify diagram type (architecture, flowchart, sequence, etc.) 2. Plan layout — identify layers, nodes, edges 3. Write SVG using Python list method (prevents truncation) 4. Validate with `python3 -c "import xml.etree.ElementTree as ET; ET.parse('file.svg')"` 5. Embed inline via `<svg>` tag (not external file) to keep the article portable ### Step 5: Write Self-Contained Article HTML **The article must be a single, standalone HTML file** with: - All CSS inlined in a single `<style>` block in `<head>` - All JS inlined in a single `<script>` block before `</body>` - No external `.css` or `.js` file references (except Google Fonts CDN, which degrades gracefully) - No reference to any `articles-data.js`, `article.js`, `main.js`, or other shared infrastructure - No `<nav id="articleNav">` (articles are independent — no prev/next navigation) - favicon as inline SVG data URI (no external favicon file) - All image paths relative: `images/hero.jpg`, `images/{section}.jpg` **Required HTML 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>{Article Title} - {Author Name}</title> <meta name="description" content="{1-2 sentence summary}"> <link rel="icon" href="data:image/svg+xml,<svg xmlns='http://www.w3.org/2000/svg' viewBox='0 0 64 64'><circle cx='32' cy='32' r='14' fill='%2300f0ff'/></svg>"> <link rel="preconnect" href="https://fonts.googleapis.com"> <link rel="preconnect" href="https://fonts.gstatic.com" crossorigin> <link href="https://fonts.googleapis.com/css2?family=Inter:wght@300;400;500;600;700&family=JetBrains+Mono:wght@400;500&display=swap" rel="stylesheet"> <style> /* ===== CSS Variables (dark theme) ===== */ :root { --bg-primary: #0a0a0f; --bg-secondary: #12121a; --bg-tertiary: #1a1a25; --text-primary: #e8e8ec; --text-secondary: #7a7a85; --text-tertiary: #4a4a55; --accent: #00f0ff; --accent-dim: rgba(0, 240, 255, 0.15); --accent-glow: rgba(0, 240, 255, 0.35); --amber: #ffb347; --divider: #2a2a35; --success: #4ade80; --danger: #f87171; --font-sans: 'Inter', -apple-system, BlinkMacSystemFont, 'Segoe UI', 'PingFang SC', 'Microsoft YaHei', sans-serif; --font-mono: 'JetBrains Mono', 'Fira Code', Consolas, monospace; --max-width: 1280px; } /* ===== Reset ===== */ * { margin: 0; padding: 0; box-sizing: border-box; } html { scroll-behavior: smooth; scroll-padding-top: 2rem; } body { font-family: var(--font-sans); background: var(--bg-primary); color: var(--text-primary); line-height: 1.75; overflow-x: hidden; -webkit-font-smoothing: antialiased; } img { max-width: 100%; height: auto; display: block; } a { color: var(--accent); text-decoration: none; } /* ===== Hero ===== */ .article-hero { position: relative; min-height: 68vh; display: flex; align-items: center; justify-content: center; padding: 8rem 2rem 4rem; overflow: hidden; } .article-hero-bg { position: absolute; inset: 0; background-size: cover; background-position: center; filter: brightness(0.5) saturate(1.15) contrast(1.05); z-index: 0; } .article-hero-overlay { position: absolute; inset: 0; background: linear-gradient(180deg, rgba(10,10,15,0.35) 0%, rgba(10,10,15,0.72) 55%, rgba(10,10,15,0.98) 100%); z-index: 1; } .article-hero-content { position: relative; z-index: 2; max-width: var(--max-width); margin: 0 auto; width: 100%; text-align: center; } .article-title { font-size: clamp(2rem, 5vw, 3.6rem); font-weight: 700; line-height: 1.15; letter-spacing: -0.02em; margin-bottom: 1.5rem; background: linear-gradient(135deg, #ffffff 0%, var(--accent) 130%); -webkit-background-clip: text; background-clip: text; -webkit-text-fill-color: transparent; } .article-meta { display: flex; align-items: center; justify-content: center; gap: 1.5rem; flex-wrap: wrap; } .article-date { color: var(--text-secondary); font-family: var(--font-mono); font-size: 0.9rem; } .article-tags { display: flex; gap: 0.6rem; flex-wrap: wrap; } .tag { padding: 0.3rem 0.85rem; background: var(--accent-dim); border: 1px solid rgba(0, 240, 255, 0.3); border-radius: 20px; font-size: 0.8rem; color: var(--accent); font-weight: 500; } /* ===== Container & Sidebar ===== */ .article-container { max-width: var(--max-width); margin: 0 auto; padding: 4rem 2rem 6rem; display: grid; grid-template-columns: 260px 1fr; gap: 4rem; } .article-sidebar { position: sticky; top: 2rem; align-self: start; max-height: calc(100vh - 4rem); overflow-y: auto; scrollbar-width: thin; scrollbar-color: var(--divider) transparent; } .article-sidebar::-webkit-scrollbar { width: 4px; } .article-sidebar::-webkit-scrollbar-thumb { background: var(--divider); border-radius: 2px; } .sidebar-section { margin-bottom: 2rem; } .sidebar-title { font-size: 0.75rem; text-transform: uppercase; letter-spacing: 0.15em; color: var(--text-tertiary); margin-bottom: 1rem; font-weight: 600; } .article-toc { list-style: none; } .article-toc li { margin-bottom: 0.35rem; } .article-toc a { display: block; padding: 0.4rem 0.8rem; color: var(--text-secondary); text-decoration: none; font-size: 0.88rem; border-left: 2px solid transparent; border-radius: 0 4px 4px 0; transition: all 0.2s ease; line-height: 1.5; } .article-toc a:hover { color: var(--accent); background: var(--accent-dim); } .article-toc a.active { color: var(--accent); border-left-color: var(--accent); background: var(--accent-dim); font-weight: 500; } /* ===== Content Typography ===== */ .article-content { min-width: 0; } .markdown-body { max-width: 760px; } .markdown-body p { margin-bottom: 1.4rem; font-size: 1.02rem; } .markdown-body h2 { font-size: 1.85rem; font-weight: 700; letter-spacing: -0.01em; margin: 3.5rem 0 1.5rem; padding-bottom: 0.8rem; border-bottom: 1px solid var(--divider); position: relative; } .markdown-body h2::before { content: ''; position: absolute; bottom: -1px; left: 0; width: 60px; height: 2px; background: var(--accent); } .markdown-body h3 { font-size: 1.3rem; font-weight: 600; margin: 2.2rem 0 1rem; } .markdown-body strong { color: var(--accent); font-weight: 600; } .markdown-body a { border-bottom: 1px dashed rgba(0, 240, 255, 0.4); } .markdown-body a:hover { border-bottom-style: solid; } .markdown-body ul, .markdown-body ol { margin: 0 0 1.4rem 1.5rem; } .markdown-body li { margin-bottom: 0.6rem; } .markdown-body code { font-family: var(--font-mono); background: var(--bg-tertiary); padding: 0.15rem 0.45rem; border-radius: 4px; font-size: 0.88em; color: var(--amber); border: 1px solid var(--divider); } .markdown-body sup a { border-bottom: none; font-size: 0.78em; vertical-align: super; }