跳转至

内容创建

本指南涵盖在 Hugo 网站上创建和管理内容的全部流程，包括博客、书籍、播客和翻译等类型。

内容类型概览

网站支持多种内容类型，每种类型有特定的功能和组织方式：

内容类型 目录 目的 特性
博客 content/*/blog/ 文章与教程 分类、标签、SEO 优化
书籍 content/*/book/ 长篇内容 章节、PDF 导出、导航
播客 content/*/podcast/ 音频内容 音频播放器、剧集管理
翻译 content/*/trans/ 翻译文章 原文追踪
页面 content/*/ 静态页面 关于、联系、自定义页面

博客

新建博客文章

  1. 生成文章文件：
# 中文博客
hugo new content/zh/blog/my-new-post.md

# 英文博客
hugo new content/en/blog/my-new-post.md
  1. 编辑 Front Matter：
---
title: "我的新博客文章"
date: 2025-01-16T10:00:00+08:00
categories:
- "技术"
- "云原生"
tags:
- "kubernetes"
- "istio"
- "服务网格"
description: "这篇文章介绍了..."
keywords:
- "关键词 1"
- "关键词 2"
image: "images/blog/my-post-banner.webp"
draft: false
---

博客 Front Matter 字段参考

字段 类型 必填 说明
title 字符串 ✅ 文章标题（SEO 重要）
date 日期时间 ✅ 发布时间
categories 数组 ✅ 文章分类
tags 数组 ✅ 文章标签
description 字符串 ✅ 元描述（SEO）
keywords 数组 ❌ SEO 关键词
image 字符串 ❌ 特色图片
draft 布尔值 ❌ 草稿状态（默认 false）
weight 整数 ❌ 文章排序
toc 布尔值 ❌ 显示目录

博客文章结构

---
# Front matter
---

# 文章标题

简要介绍文章内容。

## 概述

说明文章涵盖内容及适用读者。

## 正文

### 第一节

内容分层，合理使用标题。

### 第二节

更多内容与示例：

```bash
# 代码示例，支持语法高亮
kubectl get pods

## 结论

总结与要点。

## 参考资料

- [链接 1](https://example.com)
- [链接 2](https://example.com)

博客最佳实践

  1. SEO 优化：
  2. 标题描述性（50-60 字符）
  3. 精炼描述（150-160 字符）
  4. 关键词自然融入

  5. 合理使用标题层级

  6. 内容结构：

  7. 开头明确介绍
  8. 使用小标题分段
  9. 适当插入代码示例

  10. 结尾给出行动建议

  11. 图片与媒体：

  12. 图片采用 WebP 格式
  13. 添加 alt 文本提升无障碍
  14. 指定图片尺寸
  15. 优化文件大小

书籍

新建书籍

  1. 创建书籍目录：
mkdir -p content/zh/book/my-new-book
  1. 创建主索引文件：
hugo new content/zh/book/my-new-book/_index.md
  1. 设置书籍 Front Matter：
---
title: "我的新书"
description: "这本书介绍了..."
date: 2025-01-16
type: "book"
layout: "book"
categories:
- "技术书籍"
tags:
- "kubernetes"
- "云原生"
book_info:
  author: "Jimmy Song"
  publisher: "Self Published"
  isbn: "978-0-000000-00-0"
  pages: 200
  language: "zh"
weight: 1
---

新建章节

  1. 创建章节文件：
hugo new content/zh/book/my-new-book/chapter-01.md
hugo new content/zh/book/my-new-book/chapter-02.md
  1. 章节 Front Matter：
---
title: "第一章：介绍"
date: 2025-01-16
weight: 1
chapter: true
description: "本章介绍了..."
---

书籍组织结构

content/zh/book/my-book/
├── _index.md              # 书籍主页
├── preface.md             # 前言
├── chapter-01.md          # 第一章
├── chapter-02.md          # 第二章
├── appendix-a.md          # 附录 A
└── images/                # 书籍图片
    ├── chapter-01/
    └── chapter-02/

PDF 导出

导出书籍为 PDF：

make pdf BOOK=content/zh/book/my-book

PDF 文件会生成在 output/ 目录，具备专业排版。

播客

新建播客剧集

  1. 创建剧集文件：
hugo new content/zh/podcast/episode-001.md
  1. 设置播客 Front Matter：
---
title: "第 1 期：云原生技术趋势"
date: 2025-01-16T08:00:00+08:00
categories:
- "Jimmy Podcast"
tags:
- "云原生"
- "技术趋势"
description: "本期讨论云原生技术的最新趋势"
audio_url: "https://assets.jimmysong.io/podcasts/episode-001.mp3"
audio_type: "audio/mpeg"
duration: "25:30"
episode_number: 1
season_number: 1
episode_image_url: "https://assets.jimmysong.io/podcasts/episode-001.jpg"
transcript_url: "https://assets.jimmysong.io/podcasts/episode-001-transcript.txt"
---

播客 Front Matter 字段参考

字段 类型 必填 说明
audio_url 字符串 ✅ 音频文件地址
audio_type 字符串 ✅ MIME 类型（audio/mpeg）
duration 字符串 ✅ 时长（MM:SS）
episode_number 整数 ✅ 剧集编号
season_number 整数 ❌ 季编号
episode_image_url 字符串 ❌ 剧集封面
transcript_url 字符串 ❌ 剧集文本地址

嵌入播客播放器

在博客文章中使用 podcast shortcode 嵌入播放器：

{{< podcast episode="/zh/podcast/episode-001/" >}}

翻译

新建翻译内容

  1. 创建翻译文件：
hugo new content/zh/trans/original-article-title.md
  1. 翻译 Front Matter：
---
title: "原文标题的中文翻译"
date: 2025-01-16
categories:
- "翻译"
tags:
- "kubernetes"
- "技术文档"
description: "这是一篇翻译文章..."
original_url: "https://example.com/original-article"
original_author: "Original Author"
original_date: "2025-01-15"
translator: "Jimmy Song"
translation_date: "2025-01-16"
---

翻译规范

  1. 保持原文结构：标题层级与组织方式一致
  2. 保留技术术语：适当保留英文原词
  3. 添加译者注释：用 callout 说明
  4. 注明原作者：务必包含原文信息

内容组织

目录结构

content/
├── zh/                           # 中文内容
│   ├── blog/                    # 博客
│   │   ├── 2024/               # 按年份组织
│   │   └── 2025/
│   ├── book/                    # 书籍
│   │   ├── kubernetes-handbook/
│   │   └── istio-handbook/
│   ├── podcast/                 # 播客
│   └── trans/                   # 翻译
└── en/                          # 英文内容
    ├── blog/
    └── about/

命名规范

  1. 文件名：
  2. 小写加短横线：my-new-post.md
  3. 描述性：kubernetes-service-mesh-introduction.md

  4. 避免特殊字符和空格

  5. 图片名：

  6. 描述性命名：kubernetes-architecture-diagram.webp
  7. 加上下文：blog-post-featured-image.webp

  8. 优先使用 WebP 格式

  9. URL 结构：

  10. 简洁 URL：/blog/kubernetes-introduction/
  11. 统一模式：/book/handbook/chapter-1/
  12. SEO 友好：避免数字和特殊字符

内容增强

使用 Shortcode

利用内置 shortcode 丰富内容：

{{< callout type="info" >}}
重要信息提示。
{{< /callout >}}

{{< figure src="diagram.webp" title="架构图" >}}

{{< details title="点击展开" >}}
可展开的隐藏内容。
{{< /details >}}

{{< markmap file="mindmap.md" height="400px" >}}

添加交互元素

  1. Mermaid 图表：
```mermaid
graph TD
    A[开始] --> B{决策}
    B -->|是 | C[行动]
    B -->|否| D[结束]
```

Mermaid 图表会自动转为 SVG，提升性能与可访问性。支持流程图、时序图、甘特图等多种类型。

  1. 代码块高亮：
yaml {hl_lines=[2,4]}
apiVersion: v1
kind: Service
metadata:
  name: my-service
  1. 标签式内容：
 {{< tabs >}}
 {{< tab "YAML" >}}
 ```yaml
 key: value
 ```

 {{< /tab >}}
 {{< tab "JSON" >}}

 ```json
 {"key": "value"}
 ```

 {{< /tab >}}
 {{< /tabs >}}

SEO 优化

  1. 元信息：
  2. 标题和描述吸引人
  3. 关键词自然融入

  4. 适当添加结构化数据

  5. 内部链接：

  6. 链接相关内容
  7. 锚文本描述性

  8. 围绕主题建立内容集群

  9. 图片优化：

  10. 使用 WebP 格式
  11. 添加 alt 文本
  12. 指定尺寸
  13. 压缩文件大小

内容工作流

开发流程

  1. 规划内容：
  2. 明确目标读者
  3. 列出要点

  4. 研究关键词

  5. 创作与撰写：

  6. 选用合适内容类型
  7. 遵循 Front Matter 标准

  8. 内容清晰有吸引力

  9. 审核与编辑：

  10. 检查拼写与语法
  11. 验证链接与图片

  12. 多设备测试效果

  13. 发布与推广：

  14. 草稿设为 false
  15. 构建并部署
  16. 社交媒体宣传

质量检查清单

发布前请确认：

  • Front Matter 完整准确
  • 标题与描述符合 SEO
  • 分类与标签相关
  • 图片有 alt 文本和尺寸
  • 链接有效且相关
  • 内容符合风格规范
  • 移动端适配测试
  • 拼写语法无误

高级功能

内容分析

生成内容洞察：

npm run analytics:generate

可分析：

  • 内容表现
  • 热门话题
  • 阅读时长统计
  • SEO 指标

自动化处理

网站集成多项自动化：

  1. 图片优化：自动 WebP 转换
  2. 链接检测：自动查找坏链
  3. 内容校验：Markdown 与 Front Matter 校验
  4. 搜索索引：自动生成搜索索引

故障排查

常见内容问题

图片不显示

问题：图片无法正常展示

解决方法：

  1. 检查图片路径
  2. 确认图片目录正确
  3. 检查文件扩展名
  4. 指定图片尺寸

构建错误

问题：内容错误导致无法构建

解决方法：

  1. 检查 Front Matter 语法
  2. 校验 Markdown 格式
  3. 必填字段齐全
  4. 检查内部链接

搜索找不到内容

问题：新内容未出现在搜索结果

解决方法：

  1. 重新构建以更新索引
  2. Front Matter 包含标题和描述
  3. 内容未标记为草稿
  4. 内容目录正确

后续学习

掌握内容创建后：

相关主题

如需帮助，请查阅故障排查指南或贡献指南。