自定义图标使用示例¶

本文档展示如何在首页 CTA 按钮和主菜单中使用自定义图标。

首页 CTA 按钮示例¶

编辑 data/zh/homepage.yaml 或 data/en/homepage.yaml：

示例 1：使用自定义 SVG 图标¶

hero:
  enable: true
  title: "迈向 AI 原生应用架构时代"
  subtitle: "用系统化知识、开源实践与工程经验..."
  cta_buttons:
  - label: "进入博客"
    link: "/blog/"
    icon: "custom blog-sparkle"  # 使用 assets/media/icons/blog-sparkle.svg

  - label: "查看图书"
    link: "/book/"
    icon: "custom book-open"  # 使用 assets/media/icons/book-open.svg

  - label: "AI 开源全景图"
    link: "/ai/"
    icon: "custom ai-stars"  # 使用 assets/media/icons/ai-stars.svg

示例 2：使用 Emoji 图标¶

cta_buttons:
  - label: "进入博客"
    link: "/blog/"
    icon: "emoji ✍️"

  - label: "查看图书"
    link: "/book/"
    icon: "emoji 📚"

  - label: "AI 开源全景图"
    link: "/ai/"
    icon: "emoji 🤖"

示例 3：混合使用（保持向后兼容）¶

cta_buttons:
  - label: "进入博客"
    link: "/blog/"
    icon: "fas fa-pen-nib"  # FontAwesome（原有方式）

  - label: "查看图书"
    link: "/book/"
    icon: "custom book-open"  # 自定义 SVG

  - label: "AI 开源全景图"
    link: "/ai/"
    icon: "emoji 🤖"  # Emoji

主菜单示例¶

编辑 data/zh/homepage.yaml 的 main_menu 部分：

示例 1：使用自定义 SVG¶

main_menu:
- Name: "AI"
  URL: "/ai/"
  Pre: "custom ai-wand"  # 使用 assets/media/icons/ai-wand.svg
  Identifier: "ai"

- Name: "博客"
  URL: "/blog/"
  Pre: "custom pen-creative"  # 使用 assets/media/icons/pen-creative.svg
  Identifier: "blog"
  Params:
    mega: "blog"

- Name: "图书"
  URL: "/book/"
  Pre: "custom book-stack"  # 使用 assets/media/icons/book-stack.svg
  Identifier: "book"
  Params:
    mega: "book"

示例 2：使用 Emoji¶

main_menu:
- Name: "AI"
  URL: "/ai/"
  Pre: "emoji 🤖"

- Name: "博客"
  URL: "/blog/"
  Pre: "emoji ✍️"

- Name: "图书"
  URL: "/book/"
  Pre: "emoji 📚"

示例 3：保持原有 FontAwesome（向后兼容）¶

main_menu:
- Name: "AI"
  URL: "/ai/"
  Pre: "fas fa-wand-magic-sparkles"  # 原有方式不变

- Name: "博客"
  URL: "/blog/"
  Pre: "fas fa-pen-nib"

- Name: "图书"
  URL: "/book/"
  Pre: "fas fa-book"

创建自定义 SVG 图标¶

1. 准备 SVG 文件¶

确保 SVG 文件符合以下要求：

<svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 24 24">
  <path fill="currentColor" d="M12 2C6.48 2 2 6.48 2 12s4.48 10 10 10 10-4.48 10-10S17.52 2 12 2z"/>
</svg>

关键点：

✅ 包含 xmlns="http://www.w3.org/2000/svg"
✅ 使用 viewBox 而非固定尺寸
✅ 使用 fill="currentColor" 以继承颜色
✅ 移除不必要的元数据

2. 保存到正确位置¶

将 SVG 文件保存到以下任一位置：

推荐（支持 Hugo Pipes 优化）：

assets/media/icons/your-icon-name.svg

备用（静态文件）：

static/images/icons/your-icon-name.svg

3. 在配置中引用¶

icon: "custom your-icon-name"  # 不需要 .svg 扩展名

常见图标前缀¶

自定义 SVG¶

icon: "custom icon-name"

FontAwesome¶

# Solid（默认）
icon: "fas fa-icon-name"

# Regular
icon: "far fa-icon-name"

# Brands
icon: "fab fa-icon-name"

# Light（需要 Pro）
icon: "fal fa-icon-name"

Emoji¶

# 直接使用 emoji
icon: "emoji 🚀"

# 使用 emoji 代码
icon: "emoji :rocket:"

优化建议¶

SVG 优化工具¶

使用 SVGO 优化 SVG：

# 安装 SVGO
npm install -g svgo

# 优化单个文件
svgo input.svg -o assets/media/icons/optimized.svg

# 批量优化
svgo -f input-folder -o assets/media/icons/

图标命名规范¶

✅ 使用描述性名称：blog-sparkle、ai-stars
✅ 使用小写字母和连字符
✅ 避免使用空格和特殊字符
✅ 保持名称简短（建议 2-3 个单词）

图标风格一致性¶

保持所有图标使用相同的线条粗细
统一圆角样式
使用一致的 viewBox 尺寸（推荐 0 0 24 24）
保持相似的视觉重量

故障排除¶

图标不显示¶

检查文件路径

# 确认文件存在
ls assets/media/icons/your-icon.svg
# 或
ls static/images/icons/your-icon.svg

检查配置语法

# 正确
icon: "custom blog-icon"

# 错误（不要包含扩展名）
icon: "custom blog-icon.svg"

验证 SVG 格式
确保包含 xmlns 属性
使用 currentColor 而非硬编码颜色

图标颜色不对¶

修改 SVG 文件，将所有 fill 属性改为 currentColor：

<!-- 修改前 -->
<path fill="#000000" d="..."/>

<!-- 修改后 -->
<path fill="currentColor" d="..."/>

图标大小异常¶

确保 SVG 有正确的 viewBox：

<!-- 推荐 -->
<svg viewBox="0 0 24 24">

<!-- 不推荐（固定尺寸） -->
<svg width="24" height="24">

实际应用示例¶

科技博客风格¶

cta_buttons:
  - label: "技术博客"
    link: "/blog/"
    icon: "custom code-brackets"

  - label: "开源项目"
    link: "/projects/"
    icon: "fab fa-github"

  - label: "文档中心"
    link: "/docs/"
    icon: "custom docs-stack"

AI 主题风格¶

cta_buttons:
  - label: "AI 模型库"
    link: "/models/"
    icon: "custom neural-network"

  - label: "算法教程"
    link: "/tutorials/"
    icon: "custom brain-circuit"

  - label: "研究论文"
    link: "/papers/"
    icon: "custom research-paper"

简约 Emoji 风格¶

cta_buttons:
  - label: "博客"
    link: "/blog/"
    icon: "emoji 📝"

  - label: "项目"
    link: "/projects/"
    icon: "emoji 🚀"

  - label: "关于"
    link: "/about/"
    icon: "emoji 👨‍💻"