创建Hugo主题：分步指南

创建Hugo主题：分步指南

April 15, 2026

Hugo是一个广受欢迎的静态网站生成器，以其速度和灵活性而闻名。它的一个强大之处在于其主题系统的可定制性。创建自己的Hugo主题，不仅能让你完全控制网站的外观和感觉，还能让你深入理解Hugo的工作原理。本指南将带你一步一步地创建你的第一个Hugo主题。

1. 准备工作与Hugo基础

在开始主题开发之前，确保你已经安装了Hugo。你可以在Hugo官网找到安装指南。

了解Hugo的基本概念至关重要，包括：

内容文件（Content Files）: 通常是Markdown格式，包含你的文章、页面等内容。
模板文件（Template Files）: Hugo使用Go模板语言来渲染你的网站。这些文件定义了页面的结构和内容如何显示。
布局（Layouts）: 模板文件被组织成不同的布局，如single.html（用于单个文章）、list.html（用于文章列表）、baseof.html（基础布局）等。
静态文件（Static Files）: 包括CSS、JavaScript、图片等，它们直接被复制到输出目录。
配置文件（Configuration File）: config.toml（或config.yaml, config.json）用于配置网站的全局设置，包括主题。

2. 创建主题目录结构

Hugo主题被放置在网站根目录下的themes文件夹中。每个主题都有自己的子目录。

首先，在你的Hugo项目根目录下创建一个themes文件夹（如果不存在）。然后，在该文件夹内为你的新主题创建一个目录，例如mytheme。

hugo new site myproject
cd myproject
mkdir themes
cd themes
mkdir mytheme
cd mytheme

在mytheme目录中，你需要创建以下基本结构：

mytheme/
├── archetypes/
├── assets/
├── data/
├── i18n/
├── layouts/
├── static/
└── theme.toml

archetypes/: 用于内容类型的默认模板。
assets/: 用于处理资源，如图片、CSS、JS等，Hugo Pipes可以在这里进行转换和优化。
data/: 可以存放JSON或YAML文件，供模板访问。
i18n/: 用于国际化（多语言支持）。
layouts/: 这是主题的核心，包含所有的模板文件。
static/: 存放静态文件（CSS, JS, 图片等）。Hugo会直接将它们复制到输出目录。
theme.toml: 主题的元数据文件，包含主题名称、作者、版本等信息。

3. 配置`theme.toml`

在mytheme目录下创建一个theme.toml文件，并添加基本信息：

# themes/mytheme/theme.toml
name = "My Theme"
license = "MIT"
licenselink = "https://github.com/yourusername/mytheme/blob/main/LICENSE"
description = "A simple and clean Hugo theme."
homepage = "https://github.com/yourusername/mytheme"
tags = ["blog", "personal", "clean"]
version = "0.1.0"

[author]
  name = "Your Name"
  homepage = "https://yourwebsite.com"

4. 配置Hugo使用你的主题

现在，你需要告诉Hugo使用你创建的主题。编辑你项目根目录下的config.toml文件，添加一行：

# myproject/config.toml
baseURL = "http://example.org/"
languageCode = "en-us"
title = "My New Hugo Site"
theme = "mytheme" # 告诉Hugo使用哪个主题

5. 创建基础布局 (`layouts/baseof.html`)

所有页面都应该继承自一个基础布局。这有助于保持代码的 DRY（Don’t Repeat Yourself）原则。

在mytheme/layouts/目录下创建baseof.html文件：

<!-- themes/mytheme/layouts/baseof.html -->
<!DOCTYPE html>
<html lang="{{ .Site.LanguageCode }}">
<head>
    <meta charset="utf-8">
    <meta name="viewport" content="width=device-width, initial-scale=1.0">
    <title>{{ .Site.Title }} - {{ .Title }}</title>
    {{/* CSS and JS links will go here */}}
    {{ $styles := resources.Get "css/style.css" | minify | fingerprint }}
    <link rel="stylesheet" href="{{ $styles.Permalink }}">
</head>
<body>
    <header>
        <h1><a href="{{ .Site.BaseURL }}">{{ .Site.Title }}</a></h1>
        <nav>
            {{ range .Site.Menus.main }}
                <a href="{{ .URL }}">{{ .Name }}</a>
            {{ end }}
        </nav>
    </header>
    <main>
        {{ block "main" . }}
        {{ end }}
    </main>
    <footer>
        <p>&copy; {{ now.Year }} {{ .Site.Title }}. All rights reserved.</p>
    </footer>
    {{/* Link to JS files if any */}}
</body>
</html>

{{ block "main" . }} 和 {{ end }} 定义了一个可被子模板覆盖的块。
{{ .Site.LanguageCode }}, {{ .Site.Title }}, {{ .Title }} 是Hugo的模板变量。
resources.Get, minify, fingerprint 是Hugo Pipes的一部分，用于处理和优化CSS。

6. 创建首页布局 (`layouts/index.html`)

首页是用户访问你的网站时首先看到的内容。

在mytheme/layouts/目录下创建index.html文件：

<!-- themes/mytheme/layouts/index.html -->
{{ define "main" }}
    <h2>Welcome to {{ .Site.Title }}</h2>
    <p>This is the homepage of my custom Hugo theme.</p>

    <h3>Latest Posts:</h3>
    <ul>
        {{ range first 5 .Site.RegularPages.ByDate.Reverse }}
            <li>
                <a href="{{ .Permalink }}">{{ .Title }}</a> - {{ .Date.Format "2006-01-02" }}
            </li>
        {{ end }}
    </ul>
{{ end }}

{{ define "main" }} 告诉Hugo这个模板块将填充baseof.html中定义的main块。
{{ range first 5 .Site.RegularPages.ByDate.Reverse }} 循环显示最新的5篇文章。

7. 创建单页布局 (`layouts/post/single.html`)

这个布局用于显示单个博客文章。

在mytheme/layouts/post/目录下创建single.html文件：

<!-- themes/mytheme/layouts/post/single.html -->
{{ define "main" }}
    <article>
        <h1>{{ .Title }}</h1>
        <p>Published on: {{ .Date.Format "2006-01-02" }}</p>
        <div>
            {{ .Content }}
        </div>
    </article>
{{ end }}

.Content 变量会渲染Markdown文件中的内容。

8. 创建列表页布局 (`layouts/post/list.html`)

这个布局用于显示所有博客文章的列表。

在mytheme/layouts/post/目录下创建list.html文件：

<!-- themes/mytheme/layouts/post/list.html -->
{{ define "main" }}
    <h1>Blog Posts</h1>
    <ul>
        {{ range .Pages }}
            <li>
                <a href="{{ .Permalink }}">{{ .Title }}</a> - {{ .Date.Format "2006-01-02" }}
            </li>
        {{ end }}
    </ul>
{{ end }}

9. 添加静态文件 (CSS)

在mytheme/static/目录下创建css文件夹，并在其中创建一个style.css文件：

/* themes/mytheme/static/css/style.css */
body {
    font-family: sans-serif;
    line-height: 1.6;
    margin: 20px;
    background-color: #f4f4f4;
    color: #333;
}

header {
    background: #333;
    color: #fff;
    padding: 10px 0;
    text-align: center;
    margin-bottom: 20px;
}

header h1 a {
    color: #fff;
    text-decoration: none;
}

nav a {
    color: #fff;
    text-decoration: none;
    margin: 0 10px;
}

main {
    background: #fff;
    padding: 20px;
    border-radius: 5px;
    box-shadow: 0 0 10px rgba(0, 0, 0, 0.1);
}

footer {
    text-align: center;
    margin-top: 20px;
    font-size: 0.8em;
    color: #777;
}

article {
    margin-bottom: 30px;
}

article h1 {
    color: #333;
}

在baseof.html中，我们已经添加了使用Hugo Pipes来处理和链接这个CSS文件的代码。

10. 创建内容

现在，让我们为主题创建一些内容。

使用Hugo命令创建一篇新文章：

hugo new posts/my-first-post.md

编辑 content/posts/my-first-post.md：

---
title: "我的第一篇博客文章"
date: 2026-04-16
draft: false
---

这是一篇使用我新创建的Hugo主题发布的博客文章。

我们可以看到前面定义的布局是如何工作的。

*   项目符号列表
*   **粗体文字**
*   *斜体文字*

### 副标题

这里有一些额外的文本。

11. 运行Hugo服务器

回到你的项目根目录，运行：

hugo server -D

-D 标志会显示草稿（draft）状态的内容。访问 http://localhost:1313/ 即可看到你的网站。

12. 进阶主题开发

短代码（Shortcodes）: 允许你在Markdown内容中插入可重用的HTML片段。
菜单（Menus）: 通过config.toml配置导航菜单。
分类与标签（Taxonomies）: Hugo支持分类（Categories）和标签（Tags），你可以在模板中显示它们。
分页（Pagination）: 当文章列表很长时，可以实现分页功能。
搜索功能: 可以通过JavaScript库或Hugo的搜索插件实现。
多语言支持（i18n）: 使用i18n目录和lang参数来支持多语言。
Hugo Pipes: 用于处理CSS、JavaScript、图片等资源，例如压缩、合并、指纹识别。

总结

创建一个Hugo主题是一个学习过程，它能让你更深入地理解静态网站生成器的工作原理。从基础的布局开始，逐步添加功能和样式，你就可以构建出完全符合你需求的个性化网站。祝你主题开发愉快！