📖 前言

在使用 Hugo 搭建博客时，我们经常需要添加一些自定义的 HTML 内容来实现特殊的展示效果。本文将详细介绍在 Hugo 中添加自定义 HTML 的多种方法，帮助你打造更加个性化的博客。

🎯 适用场景

• 需要添加特殊样式的内容块
• 嵌入交互式组件
• 创建自定义布局
• 嵌入第三方服务（如评论系统、视频播放器等）
• 实现复杂的页面效果

📋 前置要求

1. 确保配置文件中启用了 HTML 支持

打开 config.yaml，确保有以下配置：

markup:
  goldmark:
    renderer:
      unsafe: true  # 允许在 Markdown 中使用 HTML

如果没有，请添加此配置并重启 Hugo 服务。

2. 了解项目结构

your-hugo-site/
├── config.yaml          # 配置文件
├── content/             # 内容目录
│   └── post/           # 文章目录
├── layouts/            # 布局模板
│   └── shortcodes/     # Shortcode 目录
└── static/             # 静态资源

🔧 方法一：在 Markdown 中直接嵌入 HTML

这是最简单直接的方法，适合一次性使用的 HTML 内容。

基础示例

在你的 Markdown 文章中直接写 HTML：

---
title: "我的文章"
date: 2025-10-30
---

## 普通 Markdown 内容

这是普通的 Markdown 段落。

<div style="background: #f0f0f0; padding: 20px; border-radius: 8px;">
  <h3>自定义 HTML 区域</h3>
  <p>这里是自定义的 HTML 内容</p>
</div>

继续 Markdown 内容...

实际效果演示

添加交互功能

你还可以添加 JavaScript 来实现交互：

创建信息面板

优缺点

优点：

• ✅ 简单直接，无需额外配置
• ✅ 适合一次性使用的内容
• ✅ 完全自由控制样式

缺点：

• ❌ 代码冗长，影响文章可读性
• ❌ 不便于复用
• ❌ 维护困难

🎨 方法二：使用 Shortcode（推荐）

Shortcode 是 Hugo 提供的一种强大的内容复用机制，可以将复杂的 HTML 封装成简单的标签。

创建 Shortcode

1. 创建卡片 Shortcode

创建文件 layouts/shortcodes/card.html：

{{- $title := .Get "title" -}}
{{- $color := .Get "color" | default "#667eea" -}}
{{- $icon := .Get "icon" | default "✨" -}}

<div style="background: linear-gradient(135deg, {{ $color }} 0%, {{ $color }}dd 100%); 
            padding: 25px; 
            border-radius: 12px; 
            color: white; 
            margin: 20px 0; 
            box-shadow: 0 4px 6px rgba(0,0,0,0.1);">
  <h3 style="margin-top: 0;">{{ $icon }} {{ $title }}</h3>
  <div style="line-height: 1.6;">
    {{ .Inner | markdownify }}
  </div>
</div>

2. 在文章中使用

{{< card title="重要提示" icon="⚡" color="#e74c3c" >}}
这是卡片中的内容，支持 **Markdown** 语法。
{{< /card >}}

效果：

更多 Shortcode 示例

提示框 Shortcode

已创建 alert shortcode，使用方法：

{{< alert type="info" title="提示" >}}
这是一条提示信息。
{{< /alert >}}

{{< alert type="success" title="成功" >}}
操作已成功完成！
{{< /alert >}}

{{< alert type="warning" title="警告" >}}
请注意相关风险。
{{< /alert >}}

{{< alert type="danger" title="危险" >}}
这是一个危险操作！
{{< /alert >}}

效果展示：

Shortcode 的优缺点

优点：

• ✅ 代码复用，提高效率
• ✅ 保持文章内容整洁
• ✅ 便于统一管理和更新
• ✅ 支持参数化配置
• ✅ 可以嵌套使用

缺点：

• ❌ 需要创建额外的文件
• ❌ 首次使用有一定学习成本

🎪 方法三：创建自定义布局模板

如果你需要创建完全自定义的页面布局，可以创建自定义模板。

创建自定义单页模板

1. 创建 layouts/page/custom.html：

{{ define "main" }}
<article class="custom-page">
  <header>
    <h1>{{ .Title }}</h1>
  </header>
  
  <div class="custom-content">
    <!-- 你的自定义 HTML -->
    <div class="hero-section">
      <h2>欢迎来到自定义页面</h2>
    </div>
    
    <!-- 渲染 Markdown 内容 -->
    {{ .Content }}
  </div>
</article>
{{ end }}

2. 在文章的 Front Matter 中指定布局：

---
title: "自定义页面"
layout: custom
---

这里是页面内容...

📝 实践建议

1. 选择合适的方法

• 简单一次性内容：直接嵌入 HTML
• 需要复用的组件：使用 Shortcode
• 完全自定义页面：创建自定义布局

2. 样式管理建议

可以将常用样式提取到 CSS 文件中：

<!-- layouts/shortcodes/styled-card.html -->
<div class="custom-card">
  {{ .Inner | markdownify }}
</div>

/* assets/scss/custom.scss */
.custom-card {
  background: linear-gradient(135deg, #667eea 0%, #764ba2 100%);
  padding: 25px;
  border-radius: 12px;
  color: white;
  margin: 20px 0;
}

3. 响应式设计

确保你的自定义 HTML 在移动设备上也能良好显示：

<div style="display: grid; 
            grid-template-columns: repeat(auto-fit, minmax(250px, 1fr)); 
            gap: 20px;">
  <!-- 内容会自动适应屏幕大小 -->
</div>

🎯 完整示例：创建功能展示页

<div style="background: white; padding: 20px; border-radius: 8px; box-shadow: 0 2px 4px rgba(0,0,0,0.1);">
  <div style="font-size: 2em; text-align: center; margin-bottom: 10px;">🎨</div>
  <h4 style="margin: 10px 0; text-align: center; color: #667eea;">自定义样式</h4>
  <p style="color: #666; text-align: center; font-size: 0.9em;">灵活的样式定制能力</p>
</div>

<div style="background: white; padding: 20px; border-radius: 8px; box-shadow: 0 2px 4px rgba(0,0,0,0.1);">
  <div style="font-size: 2em; text-align: center; margin-bottom: 10px;">⚡</div>
  <h4 style="margin: 10px 0; text-align: center; color: #667eea;">快速渲染</h4>
  <p style="color: #666; text-align: center; font-size: 0.9em;">Hugo 超快的构建速度</p>
</div>

<div style="background: white; padding: 20px; border-radius: 8px; box-shadow: 0 2px 4px rgba(0,0,0,0.1);">
  <div style="font-size: 2em; text-align: center; margin-bottom: 10px;">📱</div>
  <h4 style="margin: 10px 0; text-align: center; color: #667eea;">响应式设计</h4>
  <p style="color: #666; text-align: center; font-size: 0.9em;">完美适配各种设备</p>
</div>

⚠️ 注意事项

1. 安全性

2. 性能考虑

• 避免在文章中引入过大的 JavaScript 库
• 尽量使用 CSS 而非 JavaScript 实现动画
• 图片等静态资源放在 static 目录

3. 可维护性

🎓 进阶技巧

1. Shortcode 参数处理

<!-- 带默认值的参数 -->
{{- $title := .Get "title" | default "默认标题" -}}

<!-- 处理内部内容 -->
{{ .Inner | markdownify }}

<!-- 条件判断 -->
{{- if .Get "showIcon" -}}
  <span>图标</span>
{{- end -}}

2. 使用 Hugo 的内置函数

<!-- 格式化日期 -->
{{ .Date.Format "2006年01月02日" }}

<!-- 获取参数 -->
{{ .Params.customField }}

<!-- 循环遍历 -->
{{ range .Params.items }}
  <li>{{ . }}</li>
{{ end }}

3. 嵌套 Shortcode

{{< card title="外层卡片" >}}
这是外层内容

{{< alert type="info" >}}
这是嵌套的提示框
{{< /alert >}}

{{< /card >}}

📚 资源推荐

🎉 总结

通过本文，你学会了三种在 Hugo 中添加自定义 HTML 的方法：