CLAUDE.md

本文件为 Claude Code (claude.ai/code) 在此仓库中工作时提供指导。

项目概述

这是一个使用 Jekyll 构建、托管在 GitHub Pages 上的个人技术博客和作品集网站。网站采用现代深色主题，具有响应式设计，包含博客文章、工具集、日记部分和集成 Gitalk 评论系统的留言板。

在线网站： https://dragonkingwhd.github.io

构建与开发命令

前置要求

常用命令

安装依赖：

bundle install

本地构建网站：

bundle exec jekyll build

本地开发服务器（带实时重载）：

bundle exec jekyll serve

网站将在 http://localhost:4000 可访问

部署到 GitHub Pages：

git add .
git commit -m "你的提交信息"
git push origin main

GitHub Pages 会在推送到 main 分支时自动构建和部署。

项目结构

核心目录

关键页面

网站结构树

网站由四大主要板块组成，每个板块都有明确的功能和文件结构：

Dragonking 的博客 (https://dragonkingwhd.github.io)
│
├── 📚 知识文章 (/blog/)
│   ├── blog.html - 博客列表页面
│   │   ├── 搜索功能 - 按标题和标签搜索
│   │   ├── 分类筛选 - 按文章分类过滤
│   │   └── 文章列表 - 显示所有博客文章
│   │
│   └── _posts/ - 博客文章集合
│       ├── 2025-08-28-welcome-to-my-blog.md
│       ├── 2025-08-28-understanding-filters-from-basics-to-design.md
│       ├── 2025-09-12-cs61a-study-plan.md
│       ├── 2025-10-25-mass-spring-damper-systems.md
│       └── ... (更多文章)
│       └── 每篇文章通过 post 布局渲染，包含：
│           ├── 文章元数据（日期、作者、分类、标签）
│           ├── 文章内容（Markdown 格式）
│           ├── 文章导航（上一篇/下一篇）
│           ├── 分享按钮（Twitter、Facebook、LinkedIn）
│           └── Gitalk 评论区
│
├── 🛠️ 实用工具 (/tools/)
│   ├── tools.html - 工具集合页面
│   │   ├── 工具导航和介绍
│   │   └── 工具列表链接
│   │
│   ├── tools/plot-viewer.html - 绘图查看器（在线版）
│   │   └── 支持数据可视化和图表展示
│   │
│   ├── tools/plot-viewer-offline.html - 绘图查看器（离线版）
│   │   └── 支持离线使用
│   │
│   ├── material-properties.html - 材料属性工具
│   │   └── 材料参数查询和计算
│   │
│   └── md-to-word.html - Markdown 转 Word 工具
│       └── 将 Markdown 文件转换为 Word 文档
│
├── ✍️ 浮生日记 (/floating-diary/)
│   ├── floating-diary.html - 日记列表页面
│   │   ├── 日记条目显示
│   │   ├── 日期排序
│   │   └── 日记列表
│   │
│   └── _diary_posts/ - 日记条目集合
│       ├── 2025-12-18-first-diary.md
│       └── ... (更多日记)
│       └── 每篇日记通过 diary 布局渲染，包含：
│           ├── 日记元数据（日期、作者）
│           ├── 日记内容
│           └── Gitalk 评论区
│
└── 💬 留言板 (/guestbook/)
    ├── guestbook.html - 留言板页面
    │   ├── 留言板介绍
    │   └── Gitalk 评论区
    │
    └── Gitalk 评论系统
        ├── GitHub OAuth 认证
        ├── 评论存储在 GitHub Issues
        └── 支持 Markdown 格式评论

配置文件

架构与关键模式

Jekyll 集合

网站使用三种主要内容类型，配置为集合：

  1. 文章 (_posts/) - 博客文章，布局：post
  2. 日记 (_diary_posts/) - 个人日记条目，布局：diary
  3. 技能 和 文档 - 用于未来扩展的额外集合

每个集合在 _config.yml 中都有默认的前置元数据设置。

主题系统

网站实现了深色/浅色主题切换器，使用：

评论系统

Gitalk 集成用于文章评论：

导航与布局

样式方法

内容管理

创建博客文章

  1. 在 _posts/ 中创建新文件，命名规范：YYYY-MM-DD-title.md
  2. 添加前置元数据： 
    ---
layout: post
title: "你的标题"
date: YYYY-MM-DD HH:MM:SS +0800
categories: [分类1, 分类2]
tags: [标签1, 标签2]
author: "作者名"
excerpt: "简短描述"
---
  3. 使用 Markdown 编写内容（支持 kramdown 语法）

创建日记条目

  1. 在 _diary_posts/ 中创建新文件，命名规范：YYYY-MM-DD-title.md
  2. 添加前置元数据（类似文章，布局将为 diary）
  3. 日记条目使用相同的 Markdown 格式

前置元数据字段

重要实现细节

永久链接结构

在 _config.yml 中配置：

排除文件

以下文件在 Jekyll 构建中被排除（在 _config.yml 中）：

插件

外部服务

常见开发任务

添加新博客文章

# 在 _posts/ 中创建文件
# 添加前置元数据，layout: post
# 使用 Markdown 编写内容
# 本地测试：bundle exec jekyll serve
# 推送到 main 分支

修改样式

更新导航

编辑 _config.yml 中的 navigation 数组：

navigation:
  - title: 页面标题
    url: /page-url/
    icon: "fas fa-icon-name"

添加新页面

  1. 在根目录或子目录中创建 .html 文件
  2. 添加前置元数据，layout: default 或自定义布局
  3. 使用 Jekyll Liquid 模板语言处理动态内容

更新网站配置

编辑 _config.yml 以修改：

未来开发注意事项