# 博客主题配置文档

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

## 1. 基础配置 (`hugo.toml`)

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

*   **网站标题**: `title = '优世界'`
*   **网站链接**: `baseURL = "https://usj.cc"`
*   **语言**: `languageCode = 'zh-cn'`
*   **URL 模式**:
    *   `uglyURLs = true`: 生成以 `.html` 结尾的链接（如 `/about.html`）。
    *   **固定链接 (Permalinks)**: 文章页面使用 `slug` 作为文件名。
        ```toml
        [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`)
    *   留言 (`/comment.html`)
    *   友链 (`/links.html`)
    *   朋友圈 (`/circles.html`)
    *   归档 (`/archives.html`)

## 3. 文章管理

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

*   **隐藏文章**: 在文章的 Front Matter (头部 YAML 配置) 中添加：
    ```yaml
    status: hidden
    ```
    **效果**:
    *   文章**不会**出现在首页列表。
    *   文章**不会**出现在归档页面 (Archives)。
    *   文章**不会**出现在分类/标签列表中。
    *   **但是**，可以通过直接访问链接（URL）来查看文章。

*   **草稿文章**:
    ```yaml
    draft: true
    ```
    **效果**: 文章完全不生成，除非使用 `hugo server -D` 预览。

### URL 设置
文章默认使用 `slug` 字段作为 URL 的文件名。
例如：
```yaml
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. 常用命令

*   **本地预览**:
    ```bash
    hugo server
    ```
*   **构建站点**:
    ```bash
    hugo
    ```

## 6. 辅助脚本 (PowerShell)

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

### 6.1 新建文章 (`new_post.ps1`)
自动计算下一个 `pid` 并创建新文章。

*   **用法**:
    ```powershell
    ./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` 字段。

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

### 6.3 部署脚本 (`deploy.ps1`)
集成友链检查和站点构建。

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

### 6.4 修复 Artalk 评论 ID (`scripts/fix_artalk_json.ps1`)
修复 Artalk 导出数据中 ID 类型错误导致的父子关系丢失问题。

*   **用法**:
    ```powershell
    # 基础用法（生成 _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`)。

*   **用法**:
    ```powershell
    ./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`。

*   **用法**:
    ```powershell
    ./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 并生成朋友圈数据。

*   **用法**:
    ```bash
    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`) 运行，不会阻断线上部署流程。