hugo

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

Hugo Static Site Generator

Hugo静态站点生成器

Quick Reference

快速参考

Docs: https://gohugo.io/documentation/
Forum: https://discourse.gohugo.io/
GitHub: https://github.com/gohugoio/hugo
Template functions: https://gohugo.io/functions/
Configuration: https://gohugo.io/configuration/introduction/

文档：https://gohugo.io/documentation/
论坛：https://discourse.gohugo.io/
GitHub：https://github.com/gohugoio/hugo
模板函数：https://gohugo.io/functions/
配置：https://gohugo.io/configuration/introduction/

Core Commands

核心命令

bash

hugo new site my-site        # Create new site
hugo new theme my-theme      # Create theme skeleton
hugo new content posts/my-post.md  # Create content
hugo server -D               # Dev server (include drafts)
hugo server --navigateToChanged    # Auto-navigate to changed content
hugo                         # Build site to public/
hugo --minify                # Build with minified output
hugo --gc                    # Build and clean unused cache
hugo mod init github.com/user/repo  # Initialize Hugo modules

bash

hugo new site my-site        # 创建新站点
hugo new theme my-theme      # 创建主题骨架
hugo new content posts/my-post.md  # 创建内容
hugo server -D               # 开发服务器（包含草稿）
hugo server --navigateToChanged    # 自动跳转到修改的内容
hugo                         # 构建站点到public/目录
hugo --minify                # 构建并生成压缩后的输出
hugo --gc                    # 构建并清理无用缓存
hugo mod init github.com/user/repo  # 初始化Hugo模块

Project Structure

项目结构

my-site/
├── hugo.toml              # Site configuration
├── archetypes/            # Content templates for `hugo new`
│   └── default.md
├── assets/                # Files processed by Hugo Pipes (Sass, JS, images)
├── content/               # Site content (Markdown)
├── data/                  # Data files (JSON, TOML, YAML)
├── i18n/                  # Translation strings
├── layouts/               # Templates (override theme)
├── static/                # Static files copied as-is
├── themes/                # Installed themes
└── public/                # Generated site (build output)

my-site/
├── hugo.toml              # 站点配置
├── archetypes/            # `hugo new`使用的内容模板
│   └── default.md
├── assets/                # Hugo Pipes处理的文件（Sass、JS、图片）
├── content/               # 站点内容（Markdown格式）
├── data/                  # 数据文件（JSON、TOML、YAML格式）
├── i18n/                  # 翻译字符串
├── layouts/               # 模板（覆盖主题模板）
├── static/                # 原样复制的静态文件
├── themes/                # 已安装的主题
└── public/                # 生成的站点（构建输出）

Workflow

工作流

Creating a New Site

创建新站点

Run
```
hugo new site <name>
```
to scaffold
Configure
```
hugo.toml
```
— see references/configuration.md
Add a theme (install or create custom) — see references/theme-development.md
Create content with
```
hugo new content <section>/<name>.md
```
Run
```
hugo server -D
```
for live development
Build with
```
hugo --minify
```
for production

运行
```
hugo new site <name>
```
搭建站点骨架
配置
```
hugo.toml
```
—— 参考references/configuration.md
添加主题（安装或自定义） —— 参考references/theme-development.md
使用
```
hugo new content <section>/<name>.md
```
创建内容
运行
```
hugo server -D
```
进行实时开发
使用
```
hugo --minify
```
构建生产环境站点

Theme Development

主题开发

Create custom themes or modify existing ones. See references/theme-development.md for:

Theme directory structure and skeleton
Template lookup order
Base templates (
```
baseof.html
```
) and blocks
Partials and partial caching
List and single templates
Taxonomy and term templates

创建自定义主题或修改现有主题。参考references/theme-development.md了解：

主题目录结构与骨架
模板查找顺序
基础模板（
```
baseof.html
```
）与区块
局部组件与局部组件缓存
列表与单页模板
分类法与分类项模板

Templating

模板开发

Write Go templates for layouts, partials, and shortcodes. See references/templating.md for:

Go template syntax and functions
Context (the dot
```
.
```
) and variable scoping
Range, with, if/else patterns
Custom shortcodes
Template debugging

编写用于布局、局部组件和短代码的Go模板。参考references/templating.md了解：

Go模板语法与函数
上下文（点
```
.
```
）与变量作用域
Range、With、if/else模式
自定义短代码
模板调试

Content Management

内容管理

Organize and manage site content. See references/content-management.md for:

Page bundles (leaf vs branch)
Front matter fields
Sections and taxonomies
Menus
Multilingual / i18n
Content archetypes

组织和管理站点内容。参考references/content-management.md了解：

页面捆绑（叶子型 vs 分支型）
前置元数据字段
栏目与分类法
菜单
多语言 / i18n
内容模板（archetypes）

Asset Pipeline

资源处理流水线

Process images, CSS/Sass, JavaScript, and more. See references/asset-pipeline.md for:

Image processing (resize, crop, filters, WebP)
Sass/SCSS compilation
JavaScript bundling with esbuild
Fingerprinting and SRI
PostCSS / Tailwind CSS integration

处理图片、CSS/Sass、JavaScript等文件。参考references/asset-pipeline.md了解：

图片处理（缩放、裁剪、滤镜、WebP格式）
Sass/SCSS编译
使用esbuild打包JavaScript
指纹识别与SRI
PostCSS / Tailwind CSS集成

Deployment

部署

Deploy to hosting platforms. See references/deployment.md for:

Netlify configuration
Vercel setup
Cloudflare Pages
GitHub Pages with Actions
General CI/CD patterns

部署到托管平台。参考references/deployment.md了解：

Netlify配置
Vercel设置
Cloudflare Pages
结合GitHub Actions部署到GitHub Pages
通用CI/CD模式

Best Practices

最佳实践

Keep images with content: Use page bundles (
```
index.md
```
+ images in same directory) so Hugo can process them

Use
hugo.toml
config directory for complex sites: split into

config/_default/hugo.toml

menus.toml

params.toml

Asset pipeline minimum: Always
```
minify
```
,
```
fingerprint
```
, and use
```
slice
```
for CSS/JS bundles
Override, don't fork themes: Place overriding templates in project
```
layouts/
```
— Hugo's union file system gives project files precedence over theme files
Use partials for DRY templates: Break complex templates into focused partials; use
```
partialCached
```
for expensive operations
Content organization mirrors URL structure: Top-level directories under
```
content/
```
become sections
Draft workflow: Use
```
draft: true
```
in front matter;
```
hugo server -D
```
shows drafts, production build excludes them
Use archetypes: Define content templates in
```
archetypes/
```
for consistent front matter across content types

将图片与内容放在一起：使用页面捆绑（
```
index.md
```
+ 同目录下的图片），这样Hugo可以处理它们

复杂站点使用
hugo.toml
配置目录：拆分为

config/_default/hugo.toml

、

menus.toml

、

params.toml

资源处理流水线基础操作：始终进行
```
minify
```
（压缩）、
```
fingerprint
```
（指纹识别），并使用
```
slice
```
处理CSS/JS捆绑包
覆盖而非复刻主题：将用于覆盖的模板放在项目的
```
layouts/
```
目录下——Hugo的联合文件系统会让项目文件优先于主题文件
使用局部组件实现DRY模板：将复杂模板拆分为多个专注的局部组件；对性能开销大的操作使用
```
partialCached
```
内容组织与URL结构一致：
```
content/
```
下的顶级目录会成为栏目
草稿工作流：在前置元数据中设置
```
draft: true
```
；
```
hugo server -D
```
会显示草稿，生产构建会排除它们
使用archetypes（内容模板）：在
```
archetypes/
```
中定义内容模板，确保不同内容类型的前置元数据保持一致