创建新的 Hugo 主题

这是一个关于如何从零开始创建一个新的 Hugo 主题的详尽指南。Hugo 是一个流行的静态网站生成器，以其速度和灵活性而闻名。创建自定义主题是充分利用 Hugo 功能的关键一步。

1. 理解 Hugo 主题结构

在开始编码之前，了解 Hugo 主题的基本文件和目录结构至关重要。一个典型的 Hugo 主题包含以下几个主要部分：

layouts/: 存放 Hugo 的模板文件，例如 _default/single.html（用于显示单个内容）、_default/list.html（用于显示内容列表）、index.html（网站首页）等。
static/: 存放静态资源，如 CSS 文件、JavaScript 文件、图片等。Hugo 会将这些文件直接复制到输出目录。
assets/: 存放需要 Hugo Assets Pipeline 处理的资源，例如 Sass 文件、图片优化等。
partial/: 存放可重用的模板片段，可以在其他模板中调用，提高代码复用性。
index.html: 网站的首页模板。
_index.md: 网站的首页内容文件。

2. 设置 Hugo 开发环境

首先，确保您已安装 Hugo。您可以从 Hugo 官方网站下载适合您操作系统的版本。安装完成后，创建一个新的 Hugo 站点：

hugo new site my-new-site
cd my-new-site

接下来，我们需要为我们的主题创建一个目录。通常，主题文件会放在您网站根目录下的 themes/ 文件夹中。

mkdir themes/my-theme

3. 创建主题的布局文件

layouts/ 目录是主题的核心。我们将从创建基础的布局文件开始。

themes/my-theme/layouts/_default/baseof.html: 这是所有其他布局文件的基础模板。它定义了网站的整体结构，包括 <html>, <head>, <body> 标签，以及可能存在的导航栏和页脚。

<!DOCTYPE html>
<html>
<head>
    <meta charset="utf-8">
    <meta name="viewport" content="width=device-width, initial-scale=1">
    <title>{{ .Site.Title }}</title>
    <link rel="stylesheet" href="{{ "css/style.css" | relURL }}">
</head>
<body>
    <header>
        <h1>{{ .Site.Title }}</h1>
        <nav>
            <ul>
                <li><a href="{{ "/" | relURL }}">Home</a></li>
                {{ range .Site.Menus.main }}
                <li><a href="{{ .URL }}">{{ .Name }}</a></li>
                {{ end }}
            </ul>
        </nav>
    </header>
    <main>
        {{ block "main" . }}
        {{ end }}
    </main>
    <footer>
        <p>&copy; {{ now.Year }} {{ .Site.Title }}</p>
    </footer>
</body>
</html>

themes/my-theme/layouts/_default/single.html: 这个模板用于显示单个文章或页面。它会继承 baseof.html 并填充 main 块的内容。
```
{{ define "main" }}
<article>
    <h2>{{ .Title }}</h2>
    {{ .Content }}
</article>
{{ end }}
```

themes/my-theme/layouts/_default/list.html: 这个模板用于显示文章列表，例如博客首页或分类页面。

{{ define "main" }}
<h2>{{ .Title }}</h2>
<ul>
    {{ range .Pages }}
    <li>
        <a href="{{ .RelPermalink }}">{{ .Title }}</a> - {{ .Date.Format "2006-01-02" }}
    </li>
    {{ end }}
</ul>
{{ end }}

themes/my-theme/layouts/index.html: 网站的首页模板。通常，它会显示最近的文章列表。

{{ define "main" }}
{{ range .Pages }}
    <article>
        <h2><a href="{{ .RelPermalink }}">{{ .Title }}</a></h2>
        <p>{{ .Summary }}...</p>
    </article>
{{ end }}
{{ end }}

4. 添加静态资源

我们需要为我们的主题添加一些 CSS 样式。在 themes/my-theme/static/css/ 目录下创建一个 style.css 文件。

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

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

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

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

article {
    margin-bottom: 20px;
    border-bottom: 1px solid #eee;
    padding-bottom: 20px;
}

article:last-child {
    border-bottom: none;
}

5. 配置您的 Hugo 站点

在您的网站根目录下的 config.toml (或 config.yaml, config.json) 文件中，指定您使用的主题。

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

[menu]
  [[menu.main]]
    name = "About"
    URL = "/about/"
    weight = 1
  [[menu.main]]
    name = "Contact"
    URL = "/contact/"
    weight = 2

6. 创建内容

现在，让我们为网站创建一些内容。在您的网站根目录下的 content/ 文件夹中创建文件。

content/_index.md (首页内容):

---
title: "Welcome to My Hugo Site"
---

This is the homepage of my new Hugo site. Explore the latest posts below!

content/about.md:

---
title: "About Us"
---

This is the about page. Learn more about us here.

content/posts/first-post.md:

---
title: "My First Post"
date: 2020-05-10
draft: false
---

This is the content of my first blog post. It's exciting to start writing!

content/posts/second-post.md:

---
title: "Another Post"
date: 2020-05-12
draft: false
---

This is the content of my second blog post. Hugo makes it easy to publish content.

7. 运行 Hugo 服务器

在您的网站根目录下运行以下命令来启动 Hugo 开发服务器：

hugo server -D

-D 标志会包含草稿（draft）内容。现在，您可以在浏览器中访问 http://localhost:1313/ 来查看您的新主题和内容。

8. 进阶主题开发

导航菜单: 您可以在 config.toml 中定义菜单，并在 baseof.html 中使用 {{ range .Site.Menus.main }} 来显示它们。
部分模板 (Partials): 将重复使用的 HTML 片段（如页眉、页脚）放在 themes/my-theme/layouts/partials/ 目录下，并在其他模板中使用 {{ partial "header.html" . }} 来调用。
短代码 (Shortcodes): Hugo 的短代码允许您在 Markdown 内容中嵌入复杂的 HTML 或其他逻辑。
Taxonomies: Hugo 支持分类（categories）和标签（tags），您可以创建相应的列表页面来展示它们。
Hugo Pipes: 利用 Hugo Pipes 进行 CSS 和 JavaScript 的处理、图片的优化等。

9. 部署

当您对主题满意后，运行 hugo 命令来生成静态网站。生成的文件会存放在 public/ 目录下。您可以将 public/ 目录下的内容部署到任何静态网站托管服务上，如 Netlify, Vercel, GitHub Pages 等。

创建 Hugo 主题是一个迭代的过程。通过不断尝试和学习，您可以构建出高度定制化且功能强大的网站。