Hugo Stack 主题完全指南：安装、配置、使用与维护

1
2
3

hugo new site my-blog
cd my-blog
git init

1

git submodule add https://github.com/CaiJimmy/hugo-theme-stack.git themes/stack

1

theme: stack

1
2

# 不要直接覆盖，建议参考
# themes/stack/exampleSite/config.yaml

1
2
3
4
5

baseurl: https://yourdomain.com/          # 你的网站域名，部署时必填
title: 我的博客                           # 网站标题
languageCode: zh-cn                       # 语言代码
theme: stack                              # 主题名称
paginate: 10                              # 每页文章数

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14

menu:
  main:
    - identifier: categories
      name: 分类
      url: /categories/
      weight: 1
    - identifier: tags
      name: 标签
      url: /tags/
      weight: 2
    - identifier: about
      name: 关于
      url: /about/
      weight: 3

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42

params:
  # --- 侧边栏与个人资料 ---
  subtitle: 记录技术与生活                 # 副标题
  avatar:
    enabled: true
    local: true                          # 图片是否在本地 (assets)
    src: img/avatar.png                  # 头像路径
  
  # --- 颜色模式 ---
  colorScheme:
    toggle: true                         # 是否显示切换按钮
    default: auto                        # auto, light, dark
  
  # --- 文章列表布局 ---
  mainSections:
    - posts                              # 哪些目录的文章显示在首页
  
  # --- 社交链接 ---
  socialIcons:
    - name: github
      url: https://github.com/yourname
    - name: twitter
      url: https://twitter.com/yourname
    - name: email
      url: mailto:your@email.com

  # --- 评论系统 (以 Waline 为例，也支持 Disqus, Gitalk 等) ---
  comments:
    provider: waline
    waline:
      serverURL: https://your-waline-server.vercel.app
  
  # --- 统计分析 ---
  analytics:
    provider: google
    google:
      siteTag: G-XXXXXXXXXX
  
  # --- SEO ---
  seo:
    openGraph: true
    twitterCards: false

1

hugo new posts/my-first-post.md

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13

---
title: "我的第一篇文章"
description: "这是文章摘要，会显示在卡片上"
date: 2023-10-27T10:00:00+08:00
draft: false          # 发布时改为 false
tags: ["Hugo", "教程"]
categories: ["技术"]
# 关键：特色图片 (显示在列表页卡片上)
images:
  - img/cover.jpg    # 推荐放在 page bundle 目录或 assets 目录
---

正文内容...

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56

name: Deploy Hugo Site to Pages

on:
  push:
    branches: ["main"]  # 你的源码分支
  workflow_dispatch:

permissions:
  contents: read
  pages: write
  id-token: write

concurrency:
  group: "pages"
  cancel-in-progress: false

defaults:
  run:
    shell: bash

jobs:
  build:
    runs-on: ubuntu-latest
    env:
      HUGO_VERSION: 0.120.0
    steps:
      - name: Install Hugo CLI
        run: |
          wget -O ${{ runner.temp }}/hugo.deb https://github.com/gohugoio/hugo/releases/download/v${HUGO_VERSION}/hugo_extended_${HUGO_VERSION}_linux-amd64.deb \
          && sudo dpkg -i ${{ runner.temp }}/hugo.deb
      - name: Checkout
        uses: actions/checkout@v4
        with:
          submodules: recursive  # 关键：递归拉取子模块
          fetch-depth: 0
      - name: Setup Pages
        id: pages
        uses: actions/configure-pages@v4
      - name: Build with Hugo
        run: |
          hugo --minify --baseURL "${{ steps.pages.outputs.base_url }}/"
      - name: Upload artifact
        uses: actions/upload-pages-artifact@v3
        with:
          path: ./public

  deploy:
    environment:
      name: github-pages
      url: ${{ steps.deployment.outputs.page_url }}
    runs-on: ubuntu-latest
    needs: build
    steps:
      - name: Deploy to GitHub Pages
        id: deployment
        uses: actions/deploy-pages@v4

1
2
3
4
5
6
7
8

# 进入主题目录
cd themes/stack

# 拉取最新代码
git pull origin master

# 或者在根目录执行
git submodule update --remote --merge