创建新主题：Hugo 网站开发指南

# May 16, 2026 by AI Assistant

在 Hugo 中创建一个新的主题是一个令人兴奋的过程，它能让你完全掌控网站的外观和感觉。本指南将带你一步步了解如何从零开始构建一个 Hugo 主题，从基本结构到更高级的定制。

主题的结构

Hugo 的主题遵循一定的目录结构。当你创建一个新的主题时，你会在 themes/yourtheme 目录下看到以下主要文件和文件夹：

layouts/: 存放你的 HTML 模板文件。
- _default/: 存放默认布局。
- index.html: 首页布局。
- single.html: 单篇文章布局。
- list.html: 列表页（如博客列表）布局。
- partials/: 存放可复用的模板片段，例如页眉、页脚、导航栏等。
static/: 存放静态资源，如 CSS、JavaScript、图片等。这些文件会被直接复制到网站的根目录下。
assets/: 存放需要 Hugo 管道处理的资源，例如 Sass/SCSS 文件、图片优化等。
i18n/: 存放国际化（多语言）翻译文件。
archetypes/: 存放内容类型的默认 frontmatter 模板。
data/: 存放数据文件（如 JSON, YAML），可以在模板中引用。
config.toml (或 config.yaml, config.json): 如果你想让主题拥有自己的配置选项，可以在这里定义。

第一步：创建主题目录和基本文件

首先，在你的 Hugo 项目根目录下创建一个 themes 文件夹（如果还没有的话），然后在 themes 文件夹内创建一个代表你主题的文件夹，例如 mytheme。

mkdir themes
cd themes
mkdir mytheme
cd mytheme

接下来，创建几个核心的布局文件：

mkdir layouts
cd layouts
touch index.html
touch single.html
touch list.html
touch _default/single.html # 备用
touch _default/list.html    # 备用
mkdir partials
touch partials/header.html
touch partials/footer.html

第二步：配置 Hugo 使用你的主题

在你的 Hugo 项目根目录下的 config.toml 文件中，设置 theme 参数指向你的主题名称：

baseURL = "http://example.org/"
languageCode = "en-us"
title = "My Hugo Site"
theme = "mytheme"

第三步：编写基础布局

让我们从 layouts/index.html 开始，这是你的网站首页。

<!DOCTYPE html>
<html lang="en">
<head>
    <meta charset="UTF-8">
    <meta name="viewport" content="width=device-width, initial-scale=1.0">
    <title>{{ .Site.Title }}</title>
</head>
<body>
    {{ partial "header.html" . }}

    <main>
        <h1>Welcome to {{ .Site.Title }}</h1>
        <p>This is the homepage of my new Hugo theme.</p>
    </main>

    {{ partial "footer.html" . }}
</body>
</html>

然后是 layouts/single.html，用于显示单篇文章。

<!DOCTYPE html>
<html lang="en">
<head>
    <meta charset="UTF-8">
    <meta name="viewport" content="width=device-width, initial-scale=1.0">
    <title>{{ .Title }} - {{ .Site.Title }}</title>
</head>
<body>
    {{ partial "header.html" . }}

    <main>
        <h1>{{ .Title }}</h1>
        <p>Published on: {{ .Date.Format "2006-01-02" }}</p>
        <article>
            {{ .Content }}
        </article>
    </main>

    {{ partial "footer.html" . }}
</body>
</html>

layouts/list.html 用于显示列表页面，例如博客文章列表。

<!DOCTYPE html>
<html lang="en">
<head>
    <meta charset="UTF-8">
    <meta name="viewport" content="width=device-width, initial-scale=1.0">
    <title>Blog - {{ .Site.Title }}</title>
</head>
<body>
    {{ partial "header.html" . }}

    <main>
        <h1>Blog Posts</h1>
        <ul>
            {{ range .Pages }}
            <li>
                <a href="{{ .Permalink }}">{{ .Title }}</a>
                - {{ .Date.Format "2006-01-02" }}
            </li>
            {{ end }}
        </ul>
    </main>

![creating a new](/uploads/content/57a8207c58595c1f.jpg)

    {{ partial "footer.html" . }}
</body>
</html>

现在，创建 layouts/partials/header.html 和 layouts/partials/footer.html。

partials/header.html:

<header>
    <nav>
        <a href="{{ .Site.BaseURL }}">Home</a> |
        <a href="/about/">About</a> |
        <a href="/blog/">Blog</a>
    </nav>
    <h2>{{ .Site.Title }}</h2>
</header>
<hr>

partials/footer.html:

<hr>
<footer>
    <p>&copy; {{ now.Year }} {{ .Site.Title }}. All rights reserved.</p>
</footer>

第四步：添加静态资源

在 themes/mytheme 目录下创建 static 文件夹，并在其中添加你的 CSS 文件。

cd themes/mytheme
mkdir static
cd static
mkdir css
cd css
touch style.css

在 static/css/style.css 中添加一些简单的样式：

body {
    font-family: sans-serif;
    line-height: 1.6;
    margin: 20px;
}

header, footer {
    background-color: #f4f4f4;
    padding: 10px;
    text-align: center;
}

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

main {
    margin-top: 20px;
}

现在，你需要修改你的布局文件以链接到这个 CSS 文件。例如，在 layouts/index.html 的 <head> 部分添加：

<link rel="stylesheet" href="{{ "css/style.css" | relURL }}">

relURL 是一个 Hugo 函数，用于生成相对于网站根目录的 URL。

第五步：使用 Hugo 提供的变量和函数

Hugo 提供了许多内置变量和函数，可以帮助你在模板中动态生成内容。

.Site: 包含网站的全局信息，如 .Site.Title, .Site.BaseURL, .Site.Params (自定义参数)。
.Page: 当前页面的信息，如 .Title, .Content, .Date, .Params (页面 frontmatter 参数)。
.Pages: 一个列表，包含当前上下文中的所有页面。
{{ .Content }}: 渲染 Markdown 内容。
{{ .Permalink }}: 当前页面的永久链接。
{{ .Date.Format "layout" }}: 格式化日期。
{{ range ... }}{{ end }}: 循环遍历列表。
{{ if ... }}{{ end }}: 条件判断。
{{ partial "name.html" . }}: 渲染部分模板。
{{ .Scratch.Set "key" "value" }} 和 {{ .Scratch.Get "key" }}: 临时存储变量。

第六步：处理内容类型（Archetypes）

archetypes 文件夹允许你为不同类型的内容（如博客文章、页面）定义默认的 frontmatter。

在 themes/mytheme/archetypes/ 目录下创建 default.md。

themes/mytheme/archetypes/default.md

creating a new

文件内容：

---
title: "{{ replace .File.ContentBaseName "-" " " | title }}"
date: {{ .Date }}
draft: true
---

当你在项目根目录下的 content/ 文件夹中创建新文件时，Hugo 会使用对应的内容类型（或 default.md）作为模板。例如，如果你创建 content/posts/my-first-post.md，Hugo 会使用 archetypes/default.md。

第七步：使用 Sass/SCSS

Hugo 内置了对 Sass/SCSS 的支持。你可以在 assets 文件夹中组织你的 Sass 文件。

cd themes/mytheme
mkdir assets
cd assets
mkdir sass
cd sass
touch _index.scss # 主 Sass 文件
touch _variables.scss # 变量文件
touch _header.scss # 页眉样式
touch _footer.scss # 页脚样式

在 _index.scss 中导入其他文件：

@import "variables";
@import "header";
@import "footer";

body {
    font-family: $font-stack;
    line-height: 1.6;
    margin: 20px;
    background-color: $background-color;
}

main {
    margin-top: 20px;
}

在 _variables.scss 中定义变量：

$font-stack: Helvetica, sans-serif;
$background-color: #f0f0f0;
$primary-color: #333;

在 _header.scss 和 _footer.scss 中添加相应的样式。

然后，你需要在布局文件中引用这个 Sass 文件，Hugo 会自动编译它。

<link rel="stylesheet" href="{{ "sass/_index.scss" | relURL }}">

第八步：构建和预览

在你完成主题的编写后，可以使用 Hugo 的本地服务器来预览你的网站。

在你的 Hugo 项目根目录下运行：

hugo server -D

-D 参数会显示草稿（draft）状态的内容。Hugo 会在 localhost:1313 (默认端口) 启动一个服务器。

第九步：打包和分发主题

当你对主题满意后，你可以将其打包并与他人分享。你可以将 themes/mytheme 文件夹复制到其他 Hugo 项目的 themes 目录下，或者通过 Git 仓库进行分发。

高级主题定制

国际化 (i18n): 使用 i18n/ 文件夹和 {{ i18n "key" }} 函数来支持多语言。
自定义参数: 在主题的 config.toml 或项目的 config.toml 中使用 params 来传递自定义配置给主题。
短代码 (Shortcodes): 创建自定义短代码来在 Markdown 中插入富媒体内容或交互元素。
图片处理: Hugo 的 images 管道可以用于图片处理，如调整大小、裁剪、添加水印等。

创建 Hugo 主题是一个不断学习和迭代的过程。通过实践这些步骤，你将能够构建出满足你特定需求的强大且美观的 Hugo 网站。

爱游戏(AYX)中国官方网站-感受顶级游戏魅力