博客使用指南#

本文档详细介绍博客的各项功能和使用方法

1
src/
2
├── content/
3
│   ├── posts/           # 博客文章
4
│   ├── moments/         # 日常动态
5
│   ├── album/           # 相册
6
│   ├── daohang/         # 网站导航
7
│   ├── danmu/           # 弹幕留言
8
│   ├── bangumi/         # 番组计划
9
│   ├── spec/            # 特殊页面（关于、友链等）
10
│   └── life/            # 生活记录
11
│       ├── ideas/       # 想法
12
│       ├── places/      # 地点
13
│       ├── checkin/     # 打卡
14
│       ├── routines/    # 日常规划
15
│       ├── health/
16
│       │   ├── workout/ # 运动
17
│       │   ├── sleep/  # 睡眠
18
│       │   └── food/   # 饮食
19
│       └── notebooks/   # 笔记本
20
├── pages/               # 页面路由
21
├── components/          # 组件
22
├── config/              # 配置文件
23
│   ├── siteConfig.ts    # 站点配置
24
│   ├── sidebarConfig.ts # 侧边栏配置
25
│   ├── navBarConfig.ts  # 导航栏配置
26
│   ├── commentConfig.ts # 评论配置
27
│   └── ...
28
└── i18n/                # 国际化

1
文章 (posts)  ✅ 支持  可以按主题/分类创建子文件夹，子文件夹名称即为分类
2
日常动态 (moments)  ❌ 不支持  建议扁平化管理，所有动态文件直接放在 moments/ 目录
3
运动记录 (workout)  ❌ 不支持  建议按日期命名，扁平化管理
4
睡眠记录 (sleep)  ❌ 不支持  建议按日期命名，扁平化管理
5
饮食记录 (food)  ❌ 不支持  建议按日期或简短描述命名，扁平化管理
6
奇思妙想 (ideas)  ❌ 不支持  建议扁平化管理，用标题区分不同想法
7
打卡项目 (checkin)  ❌ 不支持  每个文件代表一个打卡项目，扁平化管理
8
日常规划 (routines)  ❌ 不支持  建议扁平化管理，每个规划一个文件
9
去过的地方 (places)  ❌ 不支持  建议扁平化管理，每个地点一个文件
10
笔记本 (notebooks)  ✅ 本身就是文件夹  每个笔记本是一个文件夹，条目放在各自的文件夹内
11
番组计划 (bangumi)  ✅ 支持  建议按类型创建子文件夹：anime、book、music、game、real

3. 健康记录#

命名建议: 使用日期格式或简短的描述性名称。

1
workout/
2
├── 2026-04-20.md    # 4月20日的运动
3
├── 2026-04-18.md    # 4月18日的运动
4
└── 2026-04-15.md    # 4月15日的运动

说明:

主要按日期命名，因为每天可能有多次运动记录
如果一天有多次不同运动，可用简短描述: 2026-04-20-晨跑.md、2026-04-20-健身房.md

文章系统 (posts)#

路径#

1
src/content/posts/

创建文章#

在 src/content/posts/ 下创建 .md 或 .mdx 文件

1
title: java学习笔记下
2
description: 🥧java学习之路开启
3
image: 'https://img.f3f3.top/img/2026/05/10/47777df32b45be53db5473bd0fb17004.webp'
4
#文章封面页
5
tags:
6
  - java基础
7
category: JAVA学习
8
  #永久连接id
9
abbrlink: "20"
10
# 文章置顶
11
pinned: true
12
published: 2026-05-10 18:19:03
13
updated: 2026-05-13 10:43:03

1
posts/
2
├── 技术/
3
│   └── docker.md
4
├── 生活/
5
│   └── daily.md
6
└── 示例.md

2. 日常动态 (moments) ❌ 不支持子文件夹#

命名建议: 使用日期格式 YYYY-MM-DD.md。

1
moments/
2
├── 2026-04-20.md    # 4月20日的动态
3
├── 2026-04-19.md    # 4月19日的动态
4
└── 2026-04-18.md    # 4月18日的动态

说明:

每条动态对应一天的记录
日期格式便于按时间排序和查找
文件名只作为元数据，实际内容在 frontmatter 的 published 字段指定

不支持子文件夹分类，所有动态文件直接放在 moments/ 目录下

创建动态#

在 src/content/moments/ 下创建 .md 文件：

1
---
2
author: 团子和蛋糕
3
avatar: https://example.com/avatar.jpg
4
published: 2026-04-18
5
images: photo1.jpg, photo2.jpg, photo3.jpg
6
tags:
7
  - 日常
8
location: 上海
9
device: iPhone 15 Pro
10
---
11

12
动态正文内容...

图片使用#

将图片放入 public/images/moments/ 目录
在 frontmatter 中使用文件名引用：images: photo1.jpg, photo2.jpg

支持 jpg、png、gif、webp 格式、、

侧边栏组件#

侧边栏组件在 src/config/sidebarConfig.ts 中配置。

可用组件#

组件	说明
`profile`	用户资料卡片，显示头像、名称、简介
`announcement`	公告通知
`music`	音乐播放器（需要音乐服务配置）
`categories`	文章分类列表
`tags`	标签云
`lifeStats`	生活统计数据面板
`relationship`	恋爱/纪念日计时器
`quoteOfTheDay`	今日一言/随机语录
`recentItems`	最近更新的文章列表
`stats`	站点统计（文章数、字数等）
`calendar`	更新日历
`sidebarToc`	文章目录（仅文章页显示）
`siteHeatmap`	更新热力图
`advertisement`	广告位（可放置自定义内容

1
{
2
  type: "组件名称",
3
  enable: true,           // 是否启用
4
  position: "sticky",     // 布局位置：sticky(粘性)、normal(普通流)
5
  showOnPostPage: true,   // 是否在文章页显示
6
  showOnNonPostPage: true, // 是否在非文章页显示
7
  // 其他组件特定配置...
8
}

评论配置#

在 src/config/siteConfig.ts 中配置 Waline：

1
comment: {
2
  waline: {
3
    serverURL: "https://your-server.vercel.app",
4
    lang: "zh-CN",
5
  }
6
}

评论启用位置#

评论功能在以下位置可用：

文章详情页: 默认开启，可通过 frontmatter comment: false 关闭
日常动态页: /moments/ 页面默认开启

留言板: /guestbook/ 页面

配置文件#

siteConfig.ts#

主要配置文件，位于 src/config/siteConfig.ts

1
配置项  类型  说明
2
title  string  站点标题，显示在浏览器标签和首页
3
description  string  站点描述，用于 SEO
4
author  string  作者名称
5
avatar  string  默认头像 URL
6
themeColor  object  主题色配置
7
themeColor.hue  number  色调 0-360
8
themeColor.saturation  number  饱和度 0-100
9
navbar  array  顶部导航栏配置
10
favicon  string  网站图标路径
11
pages  object  页面开关
12
pages.sponsor  boolean  是否启用赞助页面
13
pages.guestbook  boolean  是否启用留言板
14
pages.bangumi  boolean  是否启用番组计划
15
postListLayout  string  文章列表布局：grid、list、masonry
16
pagination  object  分页配置
17
mapConfig  object  地图配置（高德地图 API）
18
comment  object  评论系统配置

navBarConfig.ts#

导航栏配置文件，位于 src/config/navBarConfig.ts

1
[
2
  { name: "首页", url: "/" },
3
  { name: "文章", url: "/posts/" },
4
  { name: "生活", url: "/life/" },
5
  {
6
    name: "工具",
7
    url: "/tools/",
8
    children: [  // 下拉菜单
9
      { name: "工具1", url: "/tools/tool1/" },
10
      { name: "工具2", url: "/tools/tool2/" },
11
    ]
12
  },
13
]

常见问题#

Q: 如何禁用某个页面？#

在 siteConfig.ts 中修改 pages 配置：

1
pages: {
2
  sponsor: false,    // 禁用赞助页
3
  guestbook: false,  // 禁用留言板
4
  bangumi: false,    // 禁用番组页
5
}

Q: 如何添加自定义页面？#

在 src/pages/ 下创建新的 .astro 文件
使用现有的 Layout 组件包装内容
在 navBarConfig.ts 中添加导航链接、

Q: 如何添加新内容类型？#
1. 在 src/content/ 下创建新的文件夹
2. 创建对应的 schema 定义（可选）
3. 在 src/pages/ 下创建展示页面
4. 更新导航配置
  
  Q: 图片应该放在哪里#
  - 文章/生活记录图片: 直接放在正文中，图片放入 public/images/ 目录
  - 生活记录图片:
    - moments: public/images/moments/
    - places: public/images/places/
  - 笔记本图片: 放入 `public/images/notebooks/

相册 (Album)#

用于展示照片集，以精美的拍立得风格呈现。

路径: src/content/album/

1
title: 2026年春天
2
subtitle: 记录春日里的美好时光
3
date: 2026-04-01
4
location: 郑州
5
cover: https://example.com/cover.jpg
6
tags:
7

8
  - 春天
9
  - 户外
10
    photos:
11
  - src: https://example.com/photo1.jpg
12
    alt: 樱花盛开
13
    caption: 校园里的樱花开了
14
  - src: https://example.com/photo2.jpg
15
    alt: 踏青
16
    caption: 和朋友一起去踏青
17

18
---
19

20
2026年的春天，记录下每一个美好的瞬间。

字段说明#

字段	类型	必填	默认值	说明
`title`	string	是	-	相册标题
`subtitle`	string	否	-	副标题/描述
`date`	string/Date	是	-	相册日期
`location`	string	否	-	拍摄地点
`cover`	string	否	-	封面图 URL
`tags`	string[]	否	[]	标签数组
`photos`	array	是	[]	照片数组
`draft`	boolean	否	false	是否为草稿

导航 (Daohang)#

用于展示常用网站链接和工具导航，支持分类管理和特色推荐。

路径: src/content/daohang/

创建导航项#

1
字段说明
2
字段  类型  必填  默认值  说明
3
name  string  是  -  网站/工具名称
4
url  string  是  -  网站链接
5
icon  string  否  -  Material Symbols 图标名
6
description  string  否  -  简短描述
7
category  string  否  未分类  分类名称
8
tags  string[]  否  []  标签数组
9
color  string  否  -  主题色（十六进制）
10
image  string  否  -  自定义图标/图片
11
featured  boolean  否  false  是否推荐展示
12
order  number  否  0  排序权重，数字越小越靠前---
13
name: Cloudflare
14
url: https://dash.cloudflare.com/
15
icon: material-symbols:cloud
16
description: 全球CDN与网络安全服务
17
category: 常用网站
18
tags: [云服务, CDN]
19
color: "#f97316"
20
image: https://example.com/icon.png
21
featured: true
22
order: 10
23
---
24

25
网站CDN加速、DNS管理、安全防护一站式平台。

1
---
2
name: Cloudflare
3
url: https://dash.cloudflare.com/
4
icon: material-symbols:cloud
5
description: 全球CDN与网络安全服务
6
category: 常用网站
7
tags: [云服务, CDN]
8
color: "#f97316"
9
image: https://example.com/icon.png
10
featured: true
11
order: 10
12
---
13

14
网站CDN加速、DNS管理、安全防护一站式平台。

Icon 图标使用#

可以使用 Material Symbol

1
icon: material-symbols:home-outline
2
icon: material-symbols:cloud
3
icon: material-symbols:code

弹幕 (Danmu)#

留言板功能，用户可以在留言板上发送弹幕风格的留言。

路径: src/content/danmu/

1
---
2
nickname: 小明
3
avatar: https://example.com/avatar.jpg
4
time: 2026-04-18
5
---
6

7
保持热爱，奔赴山海

特殊页面 (Spec)#

特殊内容页面，包括关于、关于我、友链、项目推荐、留言板等。

路径: src/content/spec/

1. 关于页面 (about.md)#

1
---
2
title: 关于我
3
description: 个人介绍页面
4
---
5

6
# 关于我 / About Me
7

8
你好！我是 **团子和蛋糕**，一个在数字世界中默默无闻的一片叶子。
9

10
## 联系方式
11

12
- GitHub: [链接](https://github.com/xxx)
13
- Email: [邮箱](mailto:example@example.com)

2. 友链页面 (friends.md)#

1
---
2
title: 友情链接
3
description: 与优秀的朋友们一起成长
4
---
5

6
## 友链信息
7

8
站点名称: 团子和蛋糕
9
站点链接: https://blog.example.com
10
头像链接: https://example.com/avatar.jpg
11

12
## 申请方式
13

14
请将网站信息发送邮件至：xxx@example.com

3. 项目推荐 (projects.md)#

1
---
2
title: 常用网站
3
description: 精选优质开源项目和工具
4
---
5

6
## 推荐说明
7

8
这里收集了我日常使用的优质项目和工具。

4. 留言板 (guestbook.md)#

1
---
2
title: 留言板
3
description: 在这里留下你的足迹
4
---
5

6
- 请保持友善和尊重
7
- 欢迎分享你的想法

高级功能配置#

许可证配置 (licenseConfig.ts)#

1
export const licenseConfig = {
2
  enable: true,
3
  default: {
4
    name: "CC BY-NC-SA 4.0",
5
    url: "https://creativecommons.org/licenses/by-nc-sa/4.0/",
6
  },
7
};

背景壁纸 (backgroundWallpaper.ts)#

1
export const backgroundWallpaper = {
2
  enable: true,
3
  url: "https://example.com/bg.jpg",
4
};

音乐播放器 (musicConfig.ts)#

1
export const musicConfig = {
2
  enable: false,
3
  server: "tencent",  // netease, tencent, xiami, kugou
4
  id: "歌曲ID",
5
  type: "song",  // song, playlist, album
6
};

头像配置 (profileConfig.ts)#

1
export const profileConfig = {
2
  enable: true,
3
  avatar: "https://example.com/avatar.jpg",
4
  name: "团子和蛋糕",
5
  bio: "在数字世界中默默无闻的一片叶子",
6
  socials: [
7
    { name: "GitHub", url: "https://github.com/xxx" },
8
    { name: "Email", url: "mailto:xxx@example.com" },
9
  ],
10
};

赞助配置 (sponsorConfig.ts)#

1
export const sponsorConfig = {
2
  enable: true,
3
  title: "赞助作者",
4
  description: "如果觉得博客对你有帮助，可以请作者喝杯咖啡~",
5
  methods: [
6
    {
7
      name: "微信支付",
8
      image: "/images/sponsor/wechat.png",
9
    },
10
    {
11
      name: "支付宝",
12
      image: "/images/sponsor/alipay.png",
13
    },
14
    {
15
      name: "爱发电",
16
      image: "/images/sponsor/afdian.png",
17
    },
18
  ],
19
};

关系计时器 (relationshipConfig.ts)#

1
export const relationshipConfig = {
2
  enable: true,
3
  startDate: "2020-01-01",  // 纪念日日期
4
  label: "在一起",           // 显示标签
5
  updateInterval: 3600000,   // 更新间隔（毫秒）
6
};

SEO 与统计#

站点配置 (siteConfig.ts)#

配置项	说明
`title`	站点标题
`subtitle`	站点副标题
`site_url`	站点 URL
`description`	站点描述（用于 SEO）
`keywords`	站点关键词
`author`	作者名称
`favicon`	网站图标

部署与维护#

构建命令#

1
npm run dev
2
npm run build
3
npm run preview
4
npm run deploy

环境变量#

可以在 .env 文件中配置：

1
PUBLIC_SITE_URL=https://your-site.com
2
PRIVATE_VARIABLE=value

音乐

音乐

博客导航