博客主题配置文档

本项目使用 Hugo 构建，主题为 Ying。以下是主要的配置说明，方便后续查阅和维护。

1. 基础配置 (hugo.toml)

位于项目根目录下，主要控制网站的全局行为。

• 网站标题: title = '优世界'
• 网站链接: baseURL = "https://usj.cc"
• 语言: languageCode = 'zh-cn'
• URL 模式:
  • uglyURLs = true: 生成以 .html 结尾的链接（如 /about.html）。
  • 固定链接 (Permalinks): 文章页面使用 slug 作为文件名。

    [permalinks]
      post = "/:slug"
    

• 分页: paginate = 6 (每页显示 6 篇文章)
• 代码高亮: 使用 tango 样式。

2. 主题参数 (themes/Ying/hugo.toml)

位于 themes/Ying/ 目录下，控制主题的外观和组件。

• 作者信息:
  • 头像: authorImage = "/image/tx7.jpg"
  • 描述: description = "不以物喜，不以己悲"
• 社交链接:
  • 在 [params] 下的 social 列表中配置 GitHub、主页、RSS 等链接。
• 菜单导航:
  • 首页 (/)
  • 关于 (/about.html)
  • 留言 (/ly.html)
  • 友链 (/links.html)
  • 朋友圈 (/circles.html)
  • 归档 (/archives.html)

3. 文章管理

文章隐藏功能

支持通过文章头部的 status 字段来控制文章是否在列表中显示。

• 隐藏文章: 在文章的 Front Matter (头部 YAML 配置) 中添加：

  status: hidden
  

  效果:

  • 文章不会出现在首页列表。
  • 文章不会出现在归档页面 (Archives)。
  • 文章不会出现在分类/标签列表中。
  • 但是，可以通过直接访问链接（URL）来查看文章。

• 草稿文章:

  draft: true
  

  效果: 文章完全不生成，除非使用 hugo server -D 预览。

URL 设置

文章默认使用 slug 字段作为 URL 的文件名。 例如：

title: "我的文章"
date: 2023-01-01
slug: "my-post"

生成的链接为: https://usj.cc/my-post.html

4. 输出格式 (RSS)

配置了全站 RSS 输出，支持非丑陋 URL (noUgly) 和固定链接。 RSS 地址: https://usj.cc/rss.xml

5. 常用命令

• 本地预览:

  hugo server
  

• 构建站点:

  hugo
  

6. 辅助脚本 (PowerShell)

项目中包含一些 PowerShell 脚本，用于简化日常维护工作。

6.1 新建文章 (new_post.ps1)

自动计算下一个 pid 并创建新文章。

• 用法:

  ./new_post.ps1
  

• 功能:
  1. 扫描 content/post 下所有文章，找到最大的 pid。
  2. 提示输入新文章的文件名（例如 my-new-post）。
  3. 创建新文件并自动插入 pid: <max_pid + 1>。

6.2 批量添加 PID (add_pid_to_posts.ps1)

为所有现有文章批量添加或更新 pid 字段。

• 用法:

  ./add_pid_to_posts.ps1
  

• 功能:
  1. 按日期对所有文章排序。
  2. 从 1 开始顺序分配 pid。
  3. 主要用于初始化或重置所有文章 ID。

6.3 部署脚本 (deploy.ps1)

集成友链检查和站点构建。

• 用法:

  ./deploy.ps1
  

• 功能:
  1. 运行 node scripts/check_links.js 检查友链健康状况。
  2. 如果检查通过，执行 hugo 构建站点。

6.4 修复 Artalk 评论 ID (scripts/fix_artalk_json.ps1)

修复 Artalk 导出数据中 ID 类型错误导致的父子关系丢失问题。

• 用法:

  # 基础用法（生成 _fixed.json 文件）
  ./scripts/fix_artalk_json.ps1 -InputFile "backup.artrans"
  
  # 指定输出文件
  ./scripts/fix_artalk_json.ps1 -InputFile "backup.artrans" -OutputFile "fixed.artrans"
  

• 功能:
  1. 读取 JSON 导出文件。
  2. 强制将所有 id 和 rid 字段转换为整数类型。
  3. 解决 Artalk 评论全部变为父评论的问题。

6.5 批量隐藏文章 (scripts/add_draft_to_hidden.ps1)

扫描所有文章，将包含 status: hidden 的文章自动标记为草稿 (draft: true)。

• 用法:

  ./scripts/add_draft_to_hidden.ps1
  

• 功能:
  1. 扫描 content/post 下所有 Markdown 文件。
  2. 如果文章包含 status: hidden 但没有 draft: true，自动添加 draft: true。
  3. 用于批量确保“隐藏”的文章不被 Hugo 生成。

6.6 自动更新友链 JSON (scripts/update_link_lite_json.ps1)

根据 themes/Ying/data/links.yaml 自动生成 themes/Ying/static/json/link_lite.json。

• 用法:

  ./scripts/update_link_lite_json.ps1
  

• 功能:
  1. 读取 YAML 格式的友链数据。
  2. 转换为 Friend-Circle-Lite 所需的 JSON 格式。
  3. 通常在部署前自动运行。

6.7 刷新多吉云 CDN (scripts/RefreshCDN.py)

用于在部署完成后自动刷新 CDN 缓存。

• 用法: 通常由 GitHub Actions 自动调用，不建议手动运行。 需要环境变量: DOGECLOUD_ACCESS_KEY, DOGECLOUD_SECRET_KEY, CDN_URL_LIST.

6.8 朋友圈数据生成 (scripts/generate_circle_data.js)

抓取友链 RSS 并生成朋友圈数据。

• 用法:

  node scripts/generate_circle_data.js
  

• 功能:
  1. 读取 themes/Ying/static/json/link_lite.json 中的友链列表。
  2. 尝试抓取每个友链的 RSS/Atom 订阅源。
  3. 提取最新文章（包含标题、链接、摘要、图片等）。
  4. 生成 themes/Ying/static/json/friend_circle_data.json 供前端展示。

7. 自动化部署 (GitHub Actions)

本项目配置了完整的 CI/CD 流程 (.github/workflows/upy.yml)，主要包含以下步骤：

1. 环境准备: 安装 Hugo, Node.js, Python, PowerShell。
2. 预构建检查:
   • 运行 update_link_lite_json.ps1 确保友链数据最新。
   • 运行 add_draft_to_hidden.ps1 确保隐藏文章安全。
3. 数据生成:
   • 运行 npm install 安装依赖。
   • 运行 generate_circle_data.js 抓取并生成朋友圈数据。
4. 构建: 运行 hugo --minify 生成静态文件。
5. 部署: 将 public 目录推送到又拍云 (UpYun)。
6. 刷新缓存: 部署成功后，调用多吉云 (DogeCloud) API 刷新 CDN 节点。

注意: 友链健康检查 (scripts/check_links.js) 仅作为本地工具 (deploy.ps1) 运行，不会阻断线上部署流程。