创建 Hugo 主题：从零开始构建您的博客

Apr 25, 2026 in 技术
hugo 主题开发前端 markdown
4 min read

在 Hugo 生态系统中，主题扮演着网站外观和用户界面的核心角色。一个精心设计和开发的主题，不仅能提升用户体验，更能直观地传达品牌形象与网站内容。本文将引导您从零开始，逐步构建一个属于自己的 Hugo 主题，涵盖从基础结构搭建到高级功能实现的整个过程。我们将深入探讨 Hugo 主题开发的方方面面，帮助您理解其工作原理，并掌握创建既美观又实用的主题的技巧。

理解 Hugo 主题结构

Hugo 的主题遵循一套标准的目录结构，这使得 Hugo 能够有效地查找和加载主题文件。一个典型的 Hugo 主题目录包含以下几个主要部分：

layouts/: 这是主题的核心，包含所有 HTML 模板文件。Hugo 在渲染页面时会根据内容类型和布局配置来查找对应的模板。
- layouts/_default/: 存放默认布局，适用于没有指定特定布局的内容。
- layouts/partials/: 存放可重用的模板片段，例如页眉、页脚、导航栏等，可以被其他布局模板引用。
- layouts/index.html: 首页的模板。
- layouts/list.html: 列表页（如博客文章列表）的模板。
- layouts/single.html: 单篇文章（如博客详情页）的模板。
static/: 存放静态资源，如 CSS 文件、JavaScript 文件、图片、字体等。Hugo 会将此目录下的所有文件直接复制到网站的根目录。
assets/: 存放需要 Hugo Assets Pipeline 处理的资源，例如 SASS/SCSS 文件、图片优化等。Hugo 会在构建过程中处理这些文件。
i18n/: 存放国际化（i18n）翻译文件，用于支持多语言网站。
archetypes/: 存放内容类型的原型文件，用于快速创建新内容时预填充 front matter。
data/: 存放数据文件（如 JSON、YAML、TOML），可以在模板中引用和使用。
theme.toml: 主题的配置文件，用于声明主题的元数据，如名称、版本、作者等。

创建您的第一个主题

首先，我们需要在 Hugo 项目的 themes/ 目录下创建一个新的文件夹来存放我们的主题。例如，我们可以创建一个名为 mytheme 的主题：

cd your-hugo-site
mkdir themes/mytheme
cd themes/mytheme

接下来，我们需要在 mytheme 目录下创建基本的主题结构。

1. theme.toml 文件

创建一个 theme.toml 文件，并添加基本信息：

name = "My Theme"
license = "MIT"
description = "A simple and clean Hugo theme."
homepage = "https://example.com/"

2. layouts/ 目录

在 mytheme 目录下创建 layouts/ 目录，并在其中创建 _default/ 和 partials/ 子目录。

mkdir layouts
mkdir layouts/_default
mkdir layouts/partials

3. layouts/_default/baseof.html

这是主题的基础布局文件。它定义了网站的整体结构，并使用 {{ block "..." . }} 和 {{ define "..." }} 来定义可被覆盖的区域。

<!DOCTYPE html>
<html lang="{{ .Site.Language.Lang }}">
<head>
    <meta charset="utf-8">
    <meta name="viewport" content="width=device-width, initial-scale=1">
    <title>{{ .Site.Title }}</title>
    {{/* Link to your CSS file */}}
    <link rel="stylesheet" href="{{ "css/style.css" | relURL }}">
</head>
<body>
    {{ partial "header.html" . }}
    <main>
        {{ block "main" . }}
            {{ .Content }}
        {{ end }}
    </main>
    {{ partial "footer.html" . }}
</body>
</html>

4. layouts/_default/list.html

此模板用于渲染内容列表页面，例如博客文章列表。

{{ define "main" }}
<h1>{{ .Title }}</h1>
<ul>
    {{ range .Pages }}
        <li><a href="{{ .Permalink }}">{{ .Title }}</a></li>
    {{ end }}
</ul>
{{ end }}

5. layouts/_default/single.html

此模板用于渲染单个内容页面，例如博客文章详情页。

{{ define "main" }}
<h1>{{ .Title }}</h1>
<p>{{ .Date.Format "2006-01-02" }}</p>
<div>
    {{ .Content }}
</div>
{{ end }}

6. layouts/partials/header.html

一个简单的页眉部分。

<header>
    <a href="{{ .Site.BaseURL }}">{{ .Site.Title }}</a>
    <nav>
        <ul>
            {{ range .Site.Menus.main }}
                <li><a href="{{ .URL }}">{{ .Name }}</a></li>
            {{ end }}
        </ul>
    </nav>
</header>

7. layouts/partials/footer.html

一个简单的页脚部分。

<footer>
    <p>&copy; {{ .Site.Params.author | default .Site.Title }} {{ now.Year }}</p>
</footer>

8. static/ 目录

创建 static/ 目录，并在其中创建 css/ 子目录。

mkdir static
mkdir static/css

9. static/css/style.css

添加一些基本的 CSS 样式。

body {
    font-family: sans-serif;
    line-height: 1.6;
    margin: 0;
    padding: 0;
}

header {
    background: #f4f4f4;
    padding: 1rem;
    text-align: center;
}

nav ul {
    list-style: none;
    padding: 0;
}

nav ul li {
    display: inline;
    margin: 0 10px;
}

main {
    padding: 20px;
}

footer {
    text-align: center;
    padding: 1rem;
    background: #f4f4f4;
    margin-top: 20px;
}

配置您的 Hugo 网站使用新主题

现在，您需要配置您的 Hugo 网站使用刚刚创建的 mytheme。编辑您项目根目录下的 config.toml (或 hugo.toml) 文件，并添加以下行：

baseURL = "http://example.org/"
languageCode = "zh-cn"
title = "我的 Hugo 网站"
theme = "mytheme"

[params]
    author = "Your Name"

创建内容

在您的 Hugo 网站的 content/ 目录下创建一些 Markdown 文件来测试您的主题。

例如，创建 content/posts/first-post.md:

---
title: "我的第一篇博客文章"
date: 2026-04-25
draft: false
---
这是一篇测试博客文章。内容会显示在 `single.html` 模板中。

创建 content/about.md:

---
title: "关于我"
date: 2026-04-25
draft: false
layout: "single" # 显式指定布局，如果 _default/single.html 适用则可省略
---
这是关于页面的内容。

使用 Hugo Assets Pipeline

Hugo 提供了强大的 Assets Pipeline 功能，允许您在构建过程中处理 CSS、JavaScript 和图片。这对于 SASS/SCSS 编译、图片缩放、JS 压缩等非常有用。

创建 assets/ 目录:

cd your-hugo-site/themes/mytheme
mkdir assets
mkdir assets/css

创建 SASS 文件: 在 assets/css/ 目录下创建 style.scss 文件。

/* assets/css/style.scss */
$primary-color: #333;
$secondary-color: #eee;

body {
    font-family: 'Arial', sans-serif;
    line-height: 1.7;
    color: $primary-color;
    background-color: #f9f9f9;
}

header {
    background-color: $secondary-color;
    padding: 1.5rem;
    text-align: center;
    box-shadow: 0 2px 4px rgba(0,0,0,0.1);
}

header a {
    color: $primary-color;
    text-decoration: none;
    font-size: 1.8rem;
    font-weight: bold;
}

nav ul {
    list-style: none;
    padding: 0;
    margin-top: 1rem;
}

nav ul li {
    display: inline-block;
    margin: 0 15px;
}

nav ul li a {
    color: $primary-color;
    text-decoration: none;
    font-size: 1.1rem;
    transition: color 0.3s ease;
}

nav ul li a:hover {
    color: #007bff;
}

main {
    max-width: 960px;
    margin: 20px auto;
    padding: 0 20px;
    background-color: #fff;
    box-shadow: 0 2px 4px rgba(0,0,0,0.1);
    border-radius: 8px;
}

h1, h2, h3 {
    color: $primary-color;
}

p {
    margin-bottom: 1rem;
}

footer {
    text-align: center;
    padding: 1.5rem;
    margin-top: 30px;
    background-color: $secondary-color;
    font-size: 0.9rem;
    color: #666;
}

修改 baseof.html: 在 layouts/_default/baseof.html 中，将 CSS 链接修改为使用 Assets Pipeline。

<!DOCTYPE html>
<html lang="{{ .Site.Language.Lang }}">
<head>
    <meta charset="utf-8">
    <meta name="viewport" content="width=device-width, initial-scale=1">
    <title>{{ .Site.Title }}</title>
    {{/* Process SCSS file through Hugo Assets */}}
    {{ $styles := resources.Get "css/style.scss" | resources.ToCSS | resources.Minify }}
    <link rel="stylesheet" href="{{ $styles.Permalink }}">
</head>
<body>
    {{ partial "header.html" . }}
    <main>
        {{ block "main" . }}
            {{ .Content }}
        {{ end }}
    </main>
    {{ partial "footer.html" . }}
</body>
</html>

Hugo 会自动处理 assets/css/style.scss，将其编译成 CSS 并压缩，然后生成一个可访问的链接。

国际化 (i18n)

要支持多语言，您需要创建 i18n/ 目录，并在其中为每种语言创建一个 .toml 文件。

例如，i18n/en.toml:

[params]
    [params.title]
        text = "My Hugo Site"

i18n/zh.toml:

[params]
    [params.title]
        text = "我的 Hugo 网站"

在模板中使用时，可以通过 {{ i18n "key" }} 来获取翻译。

高级主题功能

导航菜单: 在 config.toml 中定义菜单，并在 header.html 中使用 {{ range .Site.Menus.main }} 遍历。
分页: 对于列表页面，您可以使用 Hugo 的分页功能 (.Paginate) 来实现。
Taxonomies: 支持分类 (categories) 和标签 (tags)。
Shortcodes: 创建自定义的短代码，方便在 Markdown 内容中插入复杂 HTML 或其他逻辑。

部署与发布

完成主题开发后，您可以使用 hugo 命令来构建您的网站。构建完成后，将 public/ 目录下的内容部署到您的 Web 服务器或托管服务上。

总结

创建一个 Hugo 主题是一个循序渐进的过程。从理解其基本结构开始，逐步添加布局、静态资源和功能。Hugo 强大的 Assets Pipeline 和灵活的模板系统为主题开发提供了极大的便利。通过不断实践和探索，您将能够构建出满足您个性化需求的强大 Hugo 主题。