Hugo + PaperMod 博客搭建完整指南：从零到上线

# Hugo（必须 extended 版本，PaperMod 需要）
brew install hugo

# Typora（写作编辑器，付费 ~$15）
brew install --cask typora

hugo version          # 应显示 extended 字样

# 进入你打算存放博客的目录，下文以 ~/myblog 为例
cd ~
hugo new site myblog
cd myblog
git init

git submodule add --depth=1 https://github.com/adityatelange/hugo-PaperMod.git themes/PaperMod

baseURL = 'https://blog.example.com/'   # 最终域名，末尾必须带斜杠
languageCode = "zh-cn"                  # 语言代码
defaultContentLanguage = "zh"           # 默认内容语言
title = '你的博客名'                     # 站点标题（浏览器标签 / 首页大标题）
theme = 'PaperMod'                      # 主题名，对应 themes/<name>/

enableRobotsTXT = true                  # 自动生成 /robots.txt（SEO）
buildDrafts = false                     # 不构建 draft: true 的文章
buildFuture = false                     # 不构建未来日期的文章

# URL 结构：渲染成 /2026/05/my-post/
[permalinks]
posts = "/:year/:month/:slug/"

# 搜索功能需要 JSON 输出（PaperMod 的 /search/ 页面用）
[outputs]
home = ["HTML", "RSS", "JSON"]

[params]
env = "production"                      # 生产环境（启用一些性能优化）
title = "你的博客名"                     # 用于 SEO 的 title
description = "博客描述"                 # meta description（搜索结果摘要）
author = "你的名字"                      # 作者名，出现在文章 meta 行
defaultTheme = "auto"                   # 主题模式：auto / dark / light
ShowReadingTime = true                  # 显示阅读时间
ShowShareButtons = false                # 分享按钮（不需要可关）
ShowCodeCopyButtons = true              # 代码块"复制"按钮
ShowToc = true                          # 文章目录
TocOpen = false                         # 目录默认折叠
ShowBreadCrumbs = true                  # 面包屑（首页 > Posts > 文章名）
ShowPostNavLinks = true                 # 文章底部上下篇导航
ShowWordCount = true                    # 字数统计
disableScrollToTop = false              # 显示"回到顶部"按钮
disableSpecial1stPost = true            # 列表第一篇不放大，统一卡片样式
comments = true                         # 启用评论（需配 layouts/partials/comments.html，见第 14 节）

# 搜索引擎参数（fuse.js）
[params.fuseOpts]
isCaseSensitive = false
shouldSort = true
location = 0
distance = 1000
threshold = 0.3
minMatchCharLength = 1
keys = ["title", "permalink", "summary", "content"]

[params.profileMode]
enabled = false                         # 不启用首页 profile 卡片模式

# 顶部菜单（按 weight 升序排列）
[[menu.main]]
identifier = "posts"
name = "文章"
url = "/posts/"
weight = 10

[[menu.main]]
identifier = "tags"
name = "标签"
url = "/tags/"
weight = 20

[[menu.main]]
identifier = "archives"
name = "归档"
url = "/archives/"
weight = 30

[[menu.main]]
identifier = "search"
name = "搜索"
url = "/search/"
weight = 40

[[menu.main]]
identifier = "about"                    # 可选：建了 content/about.md 再启用这一项
name = "关于"
url = "/about/"
weight = 50

# 代码高亮
[markup]
[markup.highlight]
noClasses = false                       # 用 CSS 类（配合 PaperMod 高亮 CSS）
codeFences = true                       # 启用 ``` 围栏代码块
guessSyntax = true                      # 不带语言标记时自动猜
lineNos = false                         # 不显示行号
style = "monokai"                       # 高亮配色（其它见 https://xyproto.github.io/splash/docs/）
[markup.goldmark.renderer]
unsafe = true                           # 允许 Markdown 里写 HTML（图片 width / shortcode 都需要）

---
title: "{{ replace .Name "-" " " | title }}"
date: {{ .Date }}
draft: false
tags: []
description: ""
ShowToc: true
TocOpen: false
cover:
  image: ""
  alt: ""
  caption: ""
---

---
title: "归档"
layout: "archives"
url: "/archives/"
summary: archives
---

---
title: "搜索"
layout: "search"
url: "/search/"
summary: search
placeholder: "输入关键词..."
---

hugo new content posts/hello-world/index.md

hugo server -D

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.160.1
    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: Install Dart Sass
        run: sudo snap install dart-sass
      - name: Checkout
        uses: actions/checkout@v5
        with:
          submodules: recursive
          fetch-depth: 0
      - name: Setup Pages
        id: pages
        uses: actions/configure-pages@v5
      - name: Install Node.js dependencies
        run: "[[ -f package-lock.json || -f npm-shrinkwrap.json ]] && npm ci || true"
      - name: Build with Hugo
        env:
          HUGO_CACHEDIR: ${{ runner.temp }}/hugo_cache
          HUGO_ENVIRONMENT: production
          TZ: Asia/Shanghai
        run: |
          hugo \
            --gc \
            --minify \
            --baseURL "${{ steps.pages.outputs.base_url }}/"
      - name: Upload artifact
        uses: actions/upload-pages-artifact@v4
        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

public/
resources/
.hugo_build.lock
.DS_Store

git add .
git commit -m "init: hugo + papermod"
git remote add origin https://github.com/<your-username>/myblog.git
git push -u origin main

blog.example.com

baseURL = "https://blog.example.com/"

git add .
git commit -m "feat: bind custom domain"
git push

<script src="https://giscus.app/client.js"
        data-repo="<owner>/<repo>"
        data-repo-id="..."
        data-category="Comments"
        data-category-id="..."
        data-mapping="pathname"
        data-strict="0"
        data-reactions-enabled="1"
        data-emit-metadata="0"
        data-input-position="bottom"
        data-theme="preferred_color_scheme"
        data-lang="zh-CN"
        data-loading="lazy"
        crossorigin="anonymous"
        async>
</script>

comments = true