跳到主要内容

主题开发

主题是 Hugo 站点外观和功能的核心。本章将介绍如何开发和使用 Hugo 主题。

主题基础​

主题目录结构​

一个完整的 Hugo 主题具有以下结构：

themes/
└── my-theme/
    ├── archetypes/
    │   └── default.md
    ├── assets/
    │   ├── css/
    │   │   └── main.css
    │   └── js/
    │       └── main.js
    ├── layouts/
    │   ├── _default/
    │   │   ├── baseof.html
    │   │   ├── list.html
    │   │   └── single.html
    │   ├── partials/
    │   │   ├── header.html
    │   │   ├── footer.html
    │   │   └── nav.html
    │   ├── shortcodes/
    │   │   └── alert.html
    │   ├── 404.html
    │   └── index.html
    ├── static/
    │   ├── images/
    │   └── fonts/
    ├── theme.toml
    └── README.md

theme.toml 配置​

theme.toml 是主题的元数据文件：

name = "My Theme"
license = "MIT"
licenselink = "https://github.com/user/my-theme/blob/main/LICENSE"
description = "A simple Hugo theme"
homepage = "https://github.com/user/my-theme"
tags = ["blog", "minimal", "responsive"]
features = ["blog", "syntax-highlighting"]
min_version = "0.92.0"

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

[params]
  dateFormat = "2006-01-02"
  showReadingTime = true

创建基础模板​

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>{{ if .IsHome }}{{ .Site.Title }}{{ else }}{{ .Title }} | {{ .Site.Title }}{{ end }}</title>
    
    <!-- SEO Meta Tags -->
    <meta name="description" content="{{ with .Description }}{{ . }}{{ else }}{{ .Site.Params.description }}{{ end }}">
    <meta name="keywords" content="{{ with .Keywords }}{{ delimit . ", " }}{{ end }}">
    <meta name="author" content="{{ .Site.Params.author }}">
    
    <!-- Open Graph -->
    {{ template "_internal/opengraph.html" . }}
    
    <!-- Twitter Card -->
    {{ template "_internal/twitter_cards.html" . }}
    
    <!-- Favicon -->
    <link rel="icon" href="{{ "favicon.ico" | relURL }}">
    
    <!-- CSS -->
    {{ $css := resources.Get "css/main.css" | minify | fingerprint }}
    <link rel="stylesheet" href="{{ $css.Permalink }}">
    
    {{ block "head" . }}{{ end }}
</head>
<body>
    {{ partial "header.html" . }}
    
    <main>
        {{ block "main" . }}{{ end }}
    </main>
    
    {{ partial "footer.html" . }}
    
    <!-- JavaScript -->
    {{ $js := resources.Get "js/main.js" | minify | fingerprint }}
    <script src="{{ $js.Permalink }}" defer></script>
    
    {{ block "scripts" . }}{{ end }}
</body>
</html>

首页模板​

layouts/index.html：

{{ define "main" }}
<section class="hero">
    <div class="container">
        <h1>{{ .Site.Title }}</h1>
        <p>{{ .Site.Params.description }}</p>
        <a href="/posts/" class="btn">浏览文章</a>
    </div>
</section>

<section class="featured-posts">
    <div class="container">
        <h2>精选文章</h2>
        <div class="posts-grid">
            {{ range first 6 (where .Site.RegularPages "Section" "posts") }}
                {{ partial "post-card.html" . }}
            {{ end }}
        </div>
    </div>
</section>

<section class="about">
    <div class="container">
        {{ .Content }}
    </div>
</section>
{{ end }}

单页模板​

layouts/_default/single.html：

{{ define "head" }}
{{ with .Params.image }}
    <meta property="og:image" content="{{ . | absURL }}">
{{ end }}
{{ end }}

{{ define "main" }}
<article class="post">
    <header class="post-header">
        {{ with .Params.image }}
            <div class="post-cover">
                <img src="{{ . }}" alt="{{ $.Title }}">
            </div>
        {{ end }}
        
        <h1 class="post-title">{{ .Title }}</h1>
        
        <div class="post-meta">
            <time datetime="{{ .Date.Format "2006-01-02" }}">
                {{ .Date.Format "2006年01月02日" }}
            </time>
            
            {{ if .Site.Params.showReadingTime }}
                <span class="reading-time">
                    {{ .ReadingTime }} 分钟阅读
                </span>
            {{ end }}
            
            {{ with .Params.author }}
                <span class="author">{{ . }}</span>
            {{ end }}
        </div>
        
        {{ with .Params.tags }}
            <div class="post-tags">
                {{ range . }}
                    <a href="{{ "tags/" | relURL }}{{ . | urlize }}/" class="tag">{{ . }}</a>
                {{ end }}
            </div>
        {{ end }}
    </header>
    
    {{ if .Params.toc | default .Site.Params.showToc }}
        <aside class="toc">
            <h3>目录</h3>
            {{ .TableOfContents }}
        </aside>
    {{ end }}
    
    <div class="post-content">
        {{ .Content }}
    </div>
    
    <footer class="post-footer">
        {{ partial "post-nav.html" . }}
    </footer>
</article>

{{ partial "related-posts.html" . }}
{{ end }}

列表模板​

layouts/_default/list.html：

{{ define "main" }}
<div class="list-header">
    <h1>{{ .Title }}</h1>
    {{ with .Description }}
        <p class="description">{{ . }}</p>
    {{ end }}
</div>

{{ .Content }}

<div class="posts-list">
    {{ range .Paginator.Pages }}
        {{ partial "post-card.html" . }}
    {{ end }}
</div>

{{ template "_internal/pagination.html" . }}
{{ end }}

Partials 组件​

头部组件​

layouts/partials/header.html：

<header class="site-header">
    <div class="container">
        <a href="{{ .Site.BaseURL }}" class="logo">
            {{ with .Site.Params.logo }}
                <img src="{{ . }}" alt="{{ $.Site.Title }}">
            {{ else }}
                <span>{{ .Site.Title }}</span>
            {{ end }}
        </a>
        
        {{ partial "nav.html" . }}
        
        <button class="menu-toggle" aria-label="切换菜单">
            <span></span>
            <span></span>
            <span></span>
        </button>
    </div>
</header>

导航组件​

layouts/partials/nav.html：

<nav class="site-nav">
    <ul>
        {{ range .Site.Menus.main }}
            <li class="{{ if $.IsMenuCurrent "main" . }}active{{ end }}">
                <a href="{{ .URL }}">{{ .Name }}</a>
                {{ if .HasChildren }}
                    <ul class="submenu">
                        {{ range .Children }}
                            <li><a href="{{ .URL }}">{{ .Name }}</a></li>
                        {{ end }}
                    </ul>
                {{ end }}
            </li>
        {{ end }}
    </ul>
</nav>

文章卡片组件​

layouts/partials/post-card.html：

<article class="post-card">
    {{ with .Params.image }}
        <a href="{{ $.RelPermalink }}" class="post-card-image">
            <img src="{{ . }}" alt="{{ $.Title }}">
        </a>
    {{ end }}
    
    <div class="post-card-content">
        <div class="post-card-meta">
            <time datetime="{{ .Date.Format "2006-01-02" }}">
                {{ .Date.Format "2006-01-02" }}
            </time>
            {{ with .Params.categories }}
                <span class="category">{{ index . 0 }}</span>
            {{ end }}
        </div>
        
        <h2 class="post-card-title">
            <a href="{{ .RelPermalink }}">{{ .Title }}</a>
        </h2>
        
        <p class="post-card-excerpt">
            {{ .Summary | plainify | truncate 150 }}
        </p>
        
        {{ with .Params.tags }}
            <div class="post-card-tags">
                {{ range first 3 . }}
                    <span class="tag">{{ . }}</span>
                {{ end }}
            </div>
        {{ end }}
    </div>
</article>

页脚组件​

layouts/partials/footer.html：

<footer class="site-footer">
    <div class="container">
        <div class="footer-content">
            <div class="footer-section">
                <h3>{{ .Site.Title }}</h3>
                <p>{{ .Site.Params.description }}</p>
            </div>
            
            <div class="footer-section">
                <h3>快速链接</h3>
                <ul>
                    {{ range .Site.Menus.footer }}
                        <li><a href="{{ .URL }}">{{ .Name }}</a></li>
                    {{ end }}
                </ul>
            </div>
            
            <div class="footer-section">
                <h3>社交媒体</h3>
                <div class="social-links">
                    {{ with .Site.Params.github }}
                        <a href="{{ . }}" target="_blank" rel="noopener">GitHub</a>
                    {{ end }}
                    {{ with .Site.Params.twitter }}
                        <a href="{{ . }}" target="_blank" rel="noopener">Twitter</a>
                    {{ end }}
                </div>
            </div>
        </div>
        
        <div class="footer-bottom">
            <p>&copy; {{ now.Year }} {{ .Site.Title }}. 保留所有权利。</p>
            <p>由 <a href="https://gohugo.io" target="_blank" rel="noopener">Hugo</a> 驱动</p>
        </div>
    </div>
</footer>

相关文章组件​

layouts/partials/related-posts.html：

{{ $related := .Site.RegularPages.Related . | first 3 }}
{{ with $related }}
<aside class="related-posts">
    <h2>相关文章</h2>
    <div class="related-grid">
        {{ range . }}
            <article class="related-item">
                {{ with .Params.image }}
                    <img src="{{ . }}" alt="{{ $.Title }}">
                {{ end }}
                <h3><a href="{{ .RelPermalink }}">{{ .Title }}</a></h3>
                <time>{{ .Date.Format "2006-01-02" }}</time>
            </article>
        {{ end }}
    </div>
</aside>
{{ end }}

文章导航组件​

layouts/partials/post-nav.html：

<nav class="post-nav">
    {{ with .PrevInSection }}
        <a href="{{ .RelPermalink }}" class="prev">
            <span class="label">上一篇</span>
            <span class="title">{{ .Title }}</span>
        </a>
    {{ end }}
    
    {{ with .NextInSection }}
        <a href="{{ .RelPermalink }}" class="next">
            <span class="label">下一篇</span>
            <span class="title">{{ .Title }}</span>
        </a>
    {{ end }}
</nav>

CSS 组织​

使用 Assets 管理样式​

assets/css/main.css：

/* 变量定义 */
:root {
    --color-primary: #3b82f6;
    --color-text: #1f2937;
    --color-bg: #ffffff;
    --color-border: #e5e7eb;
    --font-sans: -apple-system, BlinkMacSystemFont, "Segoe UI", sans-serif;
    --font-mono: "SF Mono", Monaco, "Cascadia Code", monospace;
    --spacing-unit: 1rem;
    --max-width: 1200px;
}

/* 基础样式 */
* {
    margin: 0;
    padding: 0;
    box-sizing: border-box;
}

body {
    font-family: var(--font-sans);
    color: var(--color-text);
    background-color: var(--color-bg);
    line-height: 1.6;
}

.container {
    max-width: var(--max-width);
    margin: 0 auto;
    padding: 0 var(--spacing-unit);
}

/* 头部样式 */
.site-header {
    padding: 1.5rem 0;
    border-bottom: 1px solid var(--color-border);
}

/* 文章卡片样式 */
.post-card {
    border: 1px solid var(--color-border);
    border-radius: 8px;
    overflow: hidden;
    transition: box-shadow 0.2s;
}

.post-card:hover {
    box-shadow: 0 4px 12px rgba(0, 0, 0, 0.1);
}

/* 响应式设计 */
@media (max-width: 768px) {
    .container {
        padding: 0 1rem;
    }
    
    .posts-grid {
        grid-template-columns: 1fr;
    }
}

使用 Sass/SCSS​

assets/css/main.scss：

// 变量
$primary-color: #3b82f6;
$text-color: #1f2937;
$bg-color: #ffffff;
$border-color: #e5e7eb;

// 混入
@mixin flex-center {
    display: flex;
    align-items: center;
    justify-content: center;
}

@mixin card-shadow {
    box-shadow: 0 4px 6px -1px rgba(0, 0, 0, 0.1);
}

// 样式
.post-card {
    border: 1px solid $border-color;
    border-radius: 8px;
    
    &:hover {
        @include card-shadow;
    }
    
    &-title {
        color: $text-color;
        font-size: 1.25rem;
    }
}

在模板中引用：

{{ $scss := resources.Get "css/main.scss" | toCSS | minify | fingerprint }}
<link rel="stylesheet" href="{{ $scss.Permalink }}">

JavaScript 组织​

assets/js/main.js：

// 移动端菜单
document.addEventListener('DOMContentLoaded', function() {
    const menuToggle = document.querySelector('.menu-toggle');
    const nav = document.querySelector('.site-nav');
    
    if (menuToggle && nav) {
        menuToggle.addEventListener('click', function() {
            nav.classList.toggle('active');
            menuToggle.classList.toggle('active');
        });
    }
});

// 代码高亮行号
document.querySelectorAll('pre code').forEach((block) => {
    // 添加复制按钮
    const button = document.createElement('button');
    button.className = 'copy-button';
    button.textContent = '复制';
    button.addEventListener('click', () => {
        navigator.clipboard.writeText(block.textContent);
        button.textContent = '已复制';
        setTimeout(() => button.textContent = '复制', 2000);
    });
    block.parentNode.appendChild(button);
});

主题配置​

定义主题参数​

在 theme.toml 中定义默认参数：

[params]
  dateFormat = "2006-01-02"
  showReadingTime = true
  showToc = true
  showShareButtons = true
  mainSections = ["posts"]
  
  [params.hero]
    enable = true
    title = "欢迎来到我的博客"
    subtitle = "分享技术与生活"
    
  [params.footer]
    copyright = "保留所有权利"
    poweredBy = true

在站点配置中覆盖​

用户可以在站点的 hugo.toml 中覆盖主题参数：

[params]
  dateFormat = "2006年01月02日"
  showReadingTime = false
  
  [params.hero]
    title = "我的技术博客"

主题继承​

用户可以在不修改主题的情况下覆盖模板：

my-site/
├── layouts/
│   ├── _default/
│   │   └── single.html    # 覆盖主题的单页模板
│   └── partials/
│       └── header.html    # 覆盖主题的头部组件
└── themes/
    └── my-theme/

发布主题​

准备工作​

  1. 创建完整的 README.md
  2. 添加 LICENSE 文件
  3. 准备主题截图（static/images/screenshot.png）
  4. 准备主题预览图（static/images/tn.png）

README 模板​

# My Theme

一个简洁优雅的 Hugo 博客主题。

## 特性

- 响应式设计
- 深色模式支持
- SEO 优化
- 代码高亮
- 文章目录

## 安装

```bash
cd your-hugo-site
git submodule add https://github.com/user/my-theme.git themes/my-theme

配置​

在 hugo.toml 中添加：

theme = 'my-theme'

参数配置​

[params]
  dateFormat = "2006-01-02"
  showReadingTime = true

许可证​

MIT License


### 提交到主题库

1. Fork [hugoThemes](https://github.com/gohugoio/hugoThemes) 仓库
2. 在 `themes.txt` 中添加你的主题
3. 提交 Pull Request

## 主题组件与继承

### 组合多个主题组件

Hugo 允许将多个主题组件组合成一个完整的主题。这种方式让你可以模块化地组织主题功能：

```toml
# hugo.toml
theme = ['my-shortcodes', 'base-theme', 'hyde']

主题组件的优先级从左到右依次降低。对于任何文件、数据等，Hugo 会按照以下顺序查找：

  1. 项目目录
  2. my-shortcodes
  3. base-theme
  4. hyde

主题继承​

主题组件本身也可以在其 hugo.toml 中定义自己的主题依赖，实现主题继承：

my-theme/
├── hugo.toml          # 可以定义 theme 依赖其他主题
├── layouts/
└── ...

themes/my-theme/hugo.toml：

theme = ['parent-theme']

文件合并规则​

Hugo 对不同类型的文件使用不同的合并算法：

深度合并（按键合并）：

  • i18n/ 目录的翻译文件
  • data/ 目录的数据文件

文件级合并（选择最左边的文件）：

  • static/ 目录的静态文件
  • layouts/ 目录的模板文件
  • archetypes/ 目录的原型文件

例如，如果项目和主题都有 layouts/_default/single.html，则使用项目中的版本。

主题组件可配置项​

主题组件可以有自己的配置文件，但有一些限制。主题只能配置：

  • params（全局和语言级别）
  • menu（全局和语言级别）
  • outputformats
  • mediatypes

参数命名空间​

为什么需要命名空间​

当多个主题组件或模块同时使用时，可能会出现参数命名冲突。为了避免这种情况，主题和模块开发者应该为自己的自定义参数使用命名空间。

定义命名空间参数​

在主题的 theme.toml 或 hugo.toml 中：

[params.mytheme]
  color = "blue"
  layout = "grid"
  
[params.mytheme.hero]
  enable = true
  title = "欢迎"

用户在站点配置中覆盖：

[params.mytheme]
  color = "red"  # 覆盖主题默认值

在模板中使用命名空间参数​

{{ $theme := .Site.Params.mytheme }}

{{ with $theme.hero }}
  {{ if .enable }}
    <section class="hero">
      <h1>{{ .title }}</h1>
    </section>
  {{ end }}
{{ end }}

命名空间最佳实践​

使用主题名称作为命名空间：

# 推荐：使用主题名称
[params.papermod]
  showToc = true

# 不推荐：使用通用名称
[params.theme]
  showToc = true

嵌套组织相关参数：

[params.mytheme]
  [params.mytheme.header]
    sticky = true
    logo = "/images/logo.png"
    
  [params.mytheme.footer]
    showCopyright = true
    showPoweredBy = true
    
  [params.mytheme.post]
    showReadingTime = true
    showShareButtons = true

主题开发最佳实践​

目录结构规范​

一个专业的主题应该有清晰的目录结构：

my-theme/
├── archetypes/
│   └── default.md
├── assets/
│   ├── css/
│   │   ├── main.css
│   │   └── components/
│   │       ├── header.css
│   │       └── footer.css
│   └── js/
│       └── main.js
├── layouts/
│   ├── _default/
│   │   ├── baseof.html
│   │   ├── list.html
│   │   └── single.html
│   ├── partials/
│   │   ├── head.html
│   │   ├── header.html
│   │   ├── footer.html
│   │   └── components/
│   │       ├── card.html
│   │       └── pagination.html
│   └── shortcodes/
│       └── alert.html
├── static/
│   └── images/
├── exampleSite/        # 示例站点
│   ├── content/
│   ├── hugo.toml
│   └── ...
├── theme.toml
├── README.md
└── LICENSE

配置参数设计​

提供合理的默认值：

在 theme.toml 中定义所有可配置参数的默认值：

[params]
  # 基础设置
  dateFormat = "2006-01-02"
  showReadingTime = true
  showToc = true
  showShareButtons = true
  
  # 首页设置
  [params.home]
    showPosts = true
    postsPerPage = 10
    
  # 文章设置
  [params.post]
    showAuthor = true
    showDate = true
    showTags = true
    showPrevNext = true
    
  # 页脚设置
  [params.footer]
    showCopyright = true
    showPoweredBy = true
    showThemeCredit = true

使用参数而非硬编码：

<!-- 不推荐 -->
<span>发布于 {{ .Date.Format "2006-01-02" }}</span>

<!-- 推荐 -->
<span>发布于 {{ .Date.Format .Site.Params.dateFormat }}</span>

模板组织原则​

单一职责：每个 partial 只做一件事

partials/
├── head.html           # <head> 内容
├── header.html         # 页头
├── footer.html         # 页脚
├── nav.html            # 导航
├── post-card.html      # 文章卡片
├── pagination.html     # 分页
├── tags.html           # 标签列表
└── share-buttons.html  # 分享按钮

避免深层嵌套：

<!-- 不推荐：深层嵌套 -->
{{ if .Params.image }}
  {{ if .Params.showCaption }}
    {{ if .Params.caption }}
      <figure>
        <img src="{{ .Params.image }}">
        <figcaption>{{ .Params.caption }}</figcaption>
      </figure>
    {{ end }}
  {{ end }}
{{ end }}

<!-- 推荐：使用 with 简化 -->
{{ with .Params.image }}
  <figure>
    <img src="{{ . }}">
    {{ with $.Params.caption }}
      <figcaption>{{ . }}</figcaption>
    {{ end }}
  </figure>
{{ end }}

CSS 组织最佳实践​

使用 CSS 变量：

:root {
  /* 颜色 */
  --color-primary: #3b82f6;
  --color-text: #1f2937;
  --color-bg: #ffffff;
  
  /* 字体 */
  --font-sans: -apple-system, BlinkMacSystemFont, sans-serif;
  --font-mono: "SF Mono", Monaco, monospace;
  
  /* 间距 */
  --spacing-xs: 0.25rem;
  --spacing-sm: 0.5rem;
  --spacing-md: 1rem;
  --spacing-lg: 1.5rem;
  --spacing-xl: 2rem;
  
  /* 响应式断点 */
  --breakpoint-sm: 640px;
  --breakpoint-md: 768px;
  --breakpoint-lg: 1024px;
}

模块化 CSS：

assets/css/
├── main.css
├── base/
│   ├── reset.css
│   └── typography.css
├── components/
│   ├── buttons.css
│   ├── cards.css
│   └── forms.css
├── layout/
│   ├── header.css
│   ├── footer.css
│   └── sidebar.css
└── utilities/
    ├── spacing.css
    └── display.css

在模板中合并：

{{ $css := slice
  (resources.Get "css/base/reset.css")
  (resources.Get "css/base/typography.css")
  (resources.Get "css/components/buttons.css")
  (resources.Get "css/components/cards.css")
  (resources.Get "css/layout/header.css")
  (resources.Get "css/main.css")
  | resources.Concat "css/bundle.css"
  | minify
  | fingerprint
}}
<link rel="stylesheet" href="{{ $css.Permalink }}">

深色模式支持​

使用 CSS 变量和媒体查询实现深色模式：

:root {
  --color-bg: #ffffff;
  --color-text: #1f2937;
  --color-surface: #f3f4f6;
}

@media (prefers-color-scheme: dark) {
  :root {
    --color-bg: #1f2937;
    --color-text: #f3f4f6;
    --color-surface: #374151;
  }
}

或者使用类名切换：

[data-theme="dark"] {
  --color-bg: #1f2937;
  --color-text: #f3f4f6;
}
// 切换主题
function toggleTheme() {
  const html = document.documentElement;
  const currentTheme = html.getAttribute('data-theme');
  html.setAttribute('data-theme', currentTheme === 'dark' ? 'light' : 'dark');
}

主题测试​

创建示例站点​

在主题目录中创建 exampleSite/ 用于测试和演示：

my-theme/
└── exampleSite/
    ├── content/
    │   ├── posts/
    │   │   ├── _index.md
    │   │   └── welcome.md
    │   └── _index.md
    ├── hugo.toml
    └── static/

exampleSite/hugo.toml：

baseURL = 'https://example.org/'
theme = '../'  # 指向父目录的主题

[params]
  dateFormat = "2006-01-02"
  showReadingTime = true

运行示例站点：

cd exampleSite
hugo server

测试配置选项​

创建测试页面验证所有配置选项：

---
title: "主题测试"
layout: "test"
---

此页面用于测试主题的所有功能。

检查模板覆盖​

确保主题可以被用户正确覆盖：

test-site/
├── layouts/
│   └── _default/
│       └── single.html  # 应该覆盖主题模板
└── themes/
    └── my-theme/
        └── layouts/
            └── _default/
                └── single.html

主题调试技巧​

使用 debug 函数​

{{/* 输出变量内容 */}}
<pre>{{ debug.Dump .Params }}</pre>

{{/* 输出站点配置 */}}
<pre>{{ debug.Dump .Site.Params.mytheme }}</pre>

模板性能分析​

启用模板性能指标：

templateMetrics = true
templateMetricsHints = true

运行 hugo 后会输出每个模板的执行时间和内存使用情况。

检查未使用的模板​

printUnusedTemplates = true

常见问题排查​

模板不生效：

检查模板查找顺序和文件命名：

layouts/posts/single.html     # 优先级高
layouts/_default/single.html  # 优先级低

参数不显示：

确保使用了正确的命名空间：

<!-- 检查参数是否存在 -->
{{ with .Site.Params.mytheme }}
  {{ .color }}
{{ else }}
  参数未定义
{{ end }}

静态文件找不到：

检查 static/ 目录和 URL 路径：

<!-- 正确 -->
<link rel="icon" href="{{ "favicon.ico" | relURL }}">

<!-- 错误 -->
<link rel="icon" href="/favicon.ico">

主题文档​

README 模板​

一个完整的主题 README 应该包含：

# Theme Name

简短描述主题的特点。

![Screenshot](images/screenshot.png)

## 特性

- 特性 1
- 特性 2

## 安装

### 方式一：Git Submodule

```bash
git submodule add https://github.com/user/theme-name.git themes/theme-name

方式二：Hugo Modules​

[module]
  [[module.imports]]
    path = 'github.com/user/theme-name'

配置​

完整的配置示例：

baseURL = 'https://example.org/'
theme = 'theme-name'

[params]
  # 在此添加配置

选项​

选项说明默认值
option1描述default

短代码​

alert​

{{< alert type="warning" >}}内容{{< /alert >}}

自定义​

如何覆盖模板、添加自定义 CSS 等。

贡献​

贡献指南。

许可证​

许可证信息。


### 提供示例内容

在 `exampleSite/` 中提供丰富的示例内容：

- 不同类型的内容页面
- 各种 Front Matter 配置
- 图片、代码块等元素示例
- 分类和标签示例

## 发布和维护

### 版本管理

使用语义化版本号：

v1.0.0 # 初始版本 v1.1.0 # 新增功能 v1.1.1 # Bug 修复 v2.0.0 # 破坏性更改


### 更新日志

维护 `CHANGELOG.md`：

```markdown
# Changelog

## [1.1.0] - 2024-01-15

### Added
- 新增深色模式支持
- 新增文章目录功能

### Fixed
- 修复移动端导航问题

### Changed
- 优化 CSS 加载方式

提交到主题库​

  1. 确保主题有完整的文档和示例
  2. 准备截图（static/images/screenshot.png）
  3. 准备缩略图（static/images/tn.png）
  4. Fork hugoThemes 仓库
  5. 提交 Pull Request

小结​

本章详细介绍了 Hugo 主题开发的各个方面：

基础知识：

  • 主题目录结构和配置文件
  • 基础模板和页面模板的创建
  • Partials 组件的复用

高级特性：

  • 主题组件组合与继承
  • 参数命名空间
  • 文件合并规则

最佳实践：

  • 目录结构规范
  • 配置参数设计
  • 模板组织原则
  • CSS 组织和深色模式

测试和维护：

  • 主题测试方法
  • 调试技巧
  • 文档编写
  • 版本管理

开发一个优秀的主题需要考虑用户体验、性能优化、可定制性等多个方面。遵循最佳实践可以让主题更易于维护和扩展。

下一章将学习如何部署 Hugo 站点到各种托管平台。