视频工具页面模板使用指南

概述

TEMPLATE-video-tool.md 是一个标准化的视频工具页面模板，适用于所有文本生成视频（Text-to-Video）和图像生成视频（Image-to-Video）工具。

使用步骤

1. 复制模板

cp TEMPLATE-video-tool.md content/tools/[your-tool-slug].md

2. 替换占位符

模板中所有需要替换的内容都用方括号 [...] 标记：

基本信息

• [TOOL-SLUG] → 工具的 URL slug（例如：flux-dev-ai-video-generator）
• [Tool Name] → 工具的显示名称（例如：LTX-2 Pro）
• [Brief description...] → 简短的 SEO 友好描述
• [tool-slug] → 小写的工具 slug，用于文件路径

媒体资源

• [tool-slug]-cover.webp → 封面图片
• [tool-slug]-hero-demo.mp4 → Hero 区域的演示视频
• /models/[model-icon].svg → 模型图标

内容区域

每个 section（hero, steps, features, credits, faq）都有对应的占位符需要填充。

3. 配置模块

在 modules 数组中选择需要的页面模块：

modules:
  - hero_section # 必需：主视觉区
  - steps_section_1 # 推荐：使用步骤
  - features_section_1 # 推荐：核心功能
  - credits_section # 必需：定价信息
  - faq_section # 推荐：常见问题
  - related_section # 推荐：相关工具

可选模块：

• hero_comparison - 用于图像对比类工具
• cardComparison - 用于工具卡片预览

4. 配置 appConfig

这是最重要的部分，定义了前端表单的行为：

核心字段说明

model 字段（模型选择器）：

{
  name: 'model',
  type: 'select',
  label: 'AI Model',
  value: '[tool-slug]',  // 默认选中的模型
  cols: 2,               // 占用列数
  option: [              // 可选模型列表
    {
      value: '[tool-slug]',           // 模型值（必须匹配工具slug）
      label: '[Display Name]',        // 显示名称
      description: '[Short desc]',    // 简短描述
      icon: '/models/[icon].svg',    // 模型图标
      tags: [                         // 标签（时间、价格等）
        { icon: '/images/icon-clock.svg', label: '60s' },
        { label: '50+ credits' }
      ]
    }
  ]
}

prompt 字段（文本输入）：

{
  name: 'prompt',
  type: 'prompt',
  label: 'Prompt',
  placeholder: '[Guidance text]',
  value: '',
  height: 4,              // 文本框高度
  translateToggle: true,  // 显示翻译开关
  translateEnabled: false,
  cols: 2,
  required: 1             // 必填字段
}

常见参数字段：

• duration - 视频时长（radioGroup 类型）
• resolution - 分辨率（segmentedOptions 类型）
• aspect_ratio - 宽高比（aspectRatioSelect 类型）
• fps - 帧率（select 类型）
• generate_audio - 音频生成（switch 类型）

priceKey 属性

对于影响定价的字段，添加 priceKey: 1：

{
  name: 'duration',
  type: 'radioGroup',
  priceKey: 1,  // 标记为影响价格的字段
  // ...
}

5. 准备资源文件

需要准备的文件：

/images/
  └── [tool-slug]-cover.webp           # 封面图（用于卡片）
  └── [tool-slug]-[feature].webp       # 功能展示图（可选）

/videos/
  └── [tool-slug]-hero-demo.mp4        # Hero演示视频
  └── [tool-slug]-demo.mp4             # 其他演示视频

/models/
  └── [model-icon].svg                 # 模型图标

6. 提交配置到 API

使用脚本同步配置：

node scripts/submit-configs.js [tool-slug]

最佳实践

SEO 优化

• title 应包含关键词和品牌
• description 保持在 150-160 字符
• 所有图片必须包含 alt 属性
• 使用语义化 HTML 标签（<h1>, <h2>, <h3>）

可访问性

• 为所有媒体资源添加描述性 alt 文本
• 保持标题层级的语义正确性
• 使用清晰的 CTA 按钮文本

内容写作

• Hero description：突出核心价值主张
• Features：每个功能点简洁明了
• Steps：按逻辑顺序组织，4-6 步为宜
• FAQ：回答用户最关心的问题

定价配置

• 按常用配置到高级配置排序
• 清晰标注 credits 数量
• 考虑添加说明文字

常见场景示例

场景 1：简单文本生成视频工具

保留模块：

• hero_section
• steps_section_1
• features_section_1
• credits_section
• faq_section
• related_section

表单字段：

• model
• prompt
• duration
• aspect_ratio

场景 2：高级视频工具（支持音频、高分辨率）

额外添加：

• resolution
• fps
• generate_audio

场景 3：图像生成视频工具

额外添加：

• image（图像上传字段）
• motion_strength（运动强度）

验证清单

创建新工具页面后，检查以下项目：

• 所有 [...] 占位符都已替换
• URL slug 与文件名一致
• 图片和视频资源已准备并路径正确
• appConfig 中的 value 字段与工具 slug 匹配
• 所有图片都有 alt 文本
• HTML 标签语义正确（h1/h2/h3 层级）
• FAQ 至少包含 5 个问题
• Related section 列出了相关工具
• Credits 配置完整且准确
• 本地预览正常：npm run dev
• 配置已同步到 models.yaml
• 配置已提交到 API：node scripts/submit-configs.js

故障排查

页面不显示

• 检查 draft: false
• 检查 YAML 语法（缩进必须用空格，不能用 Tab）
• 检查 frontmatter 的分隔符 ---

模型选择器不工作

• 确保 value 与工具 slug 完全匹配
• 检查 models.yaml 和 model-config.js 是否同步

样式异常

• 清除 Hugo 缓存：rm -rf resources/
• 重新构建 Tailwind：npm run dev:generate

appConfig 解析错误

• 检查 JavaScript 对象语法（注意逗号）
• 确保字符串用引号包裹
• 数组和对象正确闭合

进阶自定义

添加自定义字段

如需添加特殊参数，在 form 数组中添加：

{
  name: 'custom_param',
  type: 'slider',          // 或其他类型
  label: 'Custom Parameter',
  value: 50,
  min: 0,
  max: 100,
  step: 1,
  cols: 2
}

支持的字段类型

• select - 下拉选择
• prompt - 文本输入
• radioGroup - 单选按钮组
• segmentedOptions - 分段选择器
• aspectRatioSelect - 宽高比选择
• switch - 开关
• slider - 滑块
• imageUpload - 图片上传

相关文档

• Hugo 模板系统：themes/vidpix-hugo/layouts/
• 模块文档：themes/vidpix-hugo/layouts/partials/article/
• 项目总体架构：/CLAUDE.md
• Hero 对比模块：/docs/HERO-COMPARISON-USAGE.md