1576 字

4 分钟

博客快速使用指南

2026-02-26

教程

/

使用指南

躺平小站 - 快速使用指南#

本文档将帮助你快速掌握博客的基本使用方法，包括发文、写日记、添加相册等核心功能。

📝 一、如何发布文章#

1. 文章存放位置#

所有文章都存放在 src/content/posts/ 目录下，每篇文章是一个独立的 .md 文件。

2. 文章格式#

每篇文章的开头必须包含 frontmatter（元数据），格式如下：

1
---
2
title: 文章标题
3
published: 2025-02-25
4
description: 文章简介，会显示在文章列表中
5
tags: [标签1, 标签2, 标签3]
6
category: 分类名称
7
draft: false
8
pinned: false
9
---
10

11
这里是文章正文内容，使用 Markdown 语法编写。

3. frontmatter 字段说明#

字段	类型	必需	说明
`title`	string	是	文章标题
`published`	date	是	发布日期，格式：YYYY-MM-DD
`description`	string	是	文章简介
`tags`	array	是	标签数组，如：`["技术", "教程"]`
`category`	string	是	分类名称，如：`"技术"`
`draft`	boolean	否	是否为草稿（true 不显示，false 显示）
`pinned`	boolean	否	是否置顶（true 置顶，false 不置顶）
`encrypted`	boolean	否	是否加密（true 加密，false 不加密）
`password`	string	否	加密密码（encrypted为true时必需）
`alias`	string	否	文章别名，自定义URL路径
`image`	string	否	文章封面图片路径
`author`	string	否	文章作者
`sourceLink`	string	否	文章源链接或参考
`licenseName`	string	否	文章内容的许可证名称

4. 示例文章#

在 src/content/posts/ 目录下创建 hello-world.md：

1
---
2
title: 我的第一篇文章
3
published: 2025-02-25
4
description: 欢迎来到我的博客
5
tags: [生活, 随笔]
6
category: 生活
7
draft: false
8
pinned: false
9
---
10

11
# 欢迎来到我的博客
12

13
这是我的第一篇文章，使用 Markdown 语法编写。
14

15
## 二级标题
16

17
- 列表项 1
18
- 列表项 2
19

20
**粗体** 和 *斜体* 文本。

5. 注意事项#

文件名建议使用英文，如：hello-world.md
文章会自动按发布日期排序，最新的在前
设置 draft: true 的文章不会显示在网站上
设置 pinned: true 的文章会固定在列表顶部

📒 二、如何写日记#

1. 日记存放位置#

日记数据存放在 src/data/diary.ts 文件中。

2. 日记格式#

在 diaryData 数组中添加新的日记对象：

1
{
2
    id: 1,                          // 日记编号（唯一，递增）
3
    content: "今天天气真好！",          // 日记内容
4
    date: "2025-02-25T14:30:00Z",  // 发布时间（ISO格式）
5
    images: ["/images/diary/1.jpg"],  // 可选：图片数组
6
    location: "北京",                  // 可选：地点
7
    mood: "开心",                      // 可选：心情
8
    tags: ["日常", "生活"]            // 可选：标签
9
}

3. 添加日记示例#

打开 src/data/diary.ts，在 diaryData 数组中添加：

1
const diaryData: DiaryItem[] = [
2
    {
3
        id: 1,
4
        content: "今天天气真好，出去散步了！",
5
        date: "2025-02-25T14:30:00Z",
6
        images: ["/images/diary/sakura.jpg"],
7
        location: "公园",
8
        mood: "开心",
9
        tags: ["日常", "生活"],
10
    },
11
    {
12
        id: 2,
13
        content: "学习了一整天，收获满满！",
14
        date: "2025-02-25T20:00:00Z",
15
        mood: "充实",
16
        tags: ["学习"],
17
    },
18
];

4. 添加日记图片#

将图片放入 public/images/diary/ 目录
在日记的 images 字段中引用图片路径

5. 注意事项#

id 必须唯一，建议递增
date 使用 ISO 格式：YYYY-MM-DDTHH:mm:ssZ
日记会自动按时间倒序显示（最新的在前）
只显示最近 30 条日记

📷 三、如何新增相册#

相册支持两种模式：本地模式（推荐）和外链模式。

方式一：本地模式（推荐）#

1. 创建相册文件夹#

在 public/images/albums/ 目录下创建一个新文件夹，例如 my-album：

1
public/images/albums/
2
└── my-album/
3
    ├── cover.jpg          # 相册封面图（必需）
4
    ├── info.json          # 相册信息文件（必需）
5
    ├── photo1.jpg         # 照片文件
6
    ├── photo2.jpg
7
    └── photo3.jpg

2. 创建 info.json#

在相册文件夹中创建 info.json 文件：

1
{
2
  "title": "我的相册",
3
  "description": "这是我的第一个相册",
4
  "date": "2025-02-25",
5
  "location": "北京",
6
  "tags": ["生活", "旅行"],
7
  "layout": "grid",
8
  "columns": 3,
9
  "hidden": false
10
}

3. 添加照片#

将照片文件（jpg、png、gif、webp等）直接放入相册文件夹即可。

4. 照片标签（可选）#

照片文件名支持标签格式：文件名_标签1_标签2.jpg

例如：

sunset_风景_傍晚.jpg - 会被识别为标签：[“风景”, “傍晚”]

方式二：外链模式#

1. 创建相册文件夹#

在 public/images/albums/ 目录下创建文件夹：

1
public/images/albums/
2
└── my-album/
3
    └── info.json

2. 创建 info.json#

1
{
2
  "mode": "external",
3
  "title": "我的相册",
4
  "description": "这是外链相册",
5
  "date": "2025-02-25",
6
  "location": "北京",
7
  "tags": ["生活", "旅行"],
8
  "cover": "https://example.com/cover.jpg",
9
  "photos": [
10
    {
11
      "src": "https://example.com/photo1.jpg",
12
      "thumbnail": "https://example.com/thumb1.jpg",
13
      "title": "照片标题",
14
      "description": "照片描述",
15
      "tags": ["风景"],
16
      "date": "2025-02-25",
17
      "width": 1920,
18
      "height": 1080
19
    }
20
  ]
21
}

info.json 字段说明#

字段	类型	必需	说明
`mode`	string	否	`local`（默认）或 `external`
`title`	string	是	相册标题
`description`	string	否	相册描述
`date`	string	否	相册日期（YYYY-MM-DD）
`location`	string	否	拍摄地点
`tags`	array	否	相册标签数组
`layout`	string	否	布局：`grid`（默认）或 `masonry`
`columns`	number	否	列数（默认3）
`hidden`	boolean	否	是否隐藏相册（默认false）
`cover`	string	外链模式必需	封面图URL
`photos`	array	外链模式必需	照片数组

注意事项#

本地模式：必须包含 cover.jpg 文件
外链模式：不需要本地图片文件，所有图片URL在 info.json 中配置
支持的图片格式：jpg、jpeg、png、gif、webp、svg、avif、bmp、tiff
相册会自动扫描，添加后刷新页面即可看到

🎨 四、常用配置#

修改网站信息#

打开 src/config.ts 文件，找到 siteConfig：

1
export const siteConfig: SiteConfig = {
2
  title: "躺平小站",           // 网站标题
3
  subtitle: "一个简单的个人博客",  // 网站副标题
4
  siteURL: "https://bk.ltai.top/", // 网站地址
5
  // ...
6
};

修改导航栏#

在 src/config.ts 中找到 navBarConfig：

1
export const navBarConfig: NavBarConfig = {
2
  links: [
3
    LinkPreset.Home,      // 主页
4
    LinkPreset.Archive,   // 归档
5
    // 添加自定义链接...
6
  ],
7
};

修改个人资料#

在 src/config.ts 中找到 profileConfig：

1
export const profileConfig: ProfileConfig = {
2
  avatar: "assets/images/avatar.webp",  // 头像路径
3
  name: "躺平小站",                    // 昵称
4
  bio: "记录生活，分享美好",            // 简介
5
  // ...
6
};

🚀 五、启动和预览#

1. 安装依赖#

1
pnpm install

2. 启动开发服务器#

1
pnpm dev

3. 访问网站#

打开浏览器访问：http://localhost:4321/

4. 修改后自动刷新#

修改任何文件后，浏览器会自动刷新显示最新内容。

📒 六、Markdown 语法指南#

本博客支持完整的 Markdown 语法，包括基础语法和扩展功能。

1. 基础语法#

标题#

1
# 一级标题
2
## 二级标题
3
### 三级标题

段落和换行#

1
这是一个段落。
2

3
这是另一个段落。
4

5
行尾添加两个空格可以<br>强制换行。

强调#

1
**粗体文本**
2
*斜体文本*
3
***粗斜体文本***
4
~~删除线文本~~

列表#

无序列表：

1
- 项目 1
2
- 项目 2
3
  - 子项目 2.1
4
  - 子项目 2.2

有序列表：

1
1. 第一项
2
2. 第二项
3
3. 第三项

引用#

1
> 这是一个引用块
2
>
3
> > 嵌套引用

代码#

行内代码：

1
使用 `code()` 函数

代码块：

1
```javascript
2
function hello() {
3
  console.log("Hello, World!");
4
}
5
```

链接和图片#

1
[链接文本](https://example.com)
2

3
![图片描述](/path/to/image.jpg)

表格#

1
| 列1 | 列2 | 列3 |
2
|-----|-----|-----|
3
| 数据1 | 数据2 | 数据3 |
4
| 数据4 | 数据5 | 数据6 |

2. 扩展功能#

提示框#

支持以下类型的提示框：note、tip、important、warning、caution

1
:::note
2
突出显示用户在浏览时应该考虑的信息。
3
:::
4

5
:::tip
6
帮助用户更成功的可选信息。
7
:::
8

9
:::important
10
用户成功所需的关键信息。
11
:::
12

13
:::warning
14
由于潜在风险需要用户立即关注的关键内容。
15
:::
16

17
:::caution
18
操作的负面潜在后果。
19
:::

自定义标题：

1
:::note[我的自定义标题]
2
这是一个带有自定义标题的提示框。
3
:::

GitHub 语法：

1
> [!NOTE]
2
GitHub语法也被支持。
3

4
> [!TIP]
5
GitHub语法也被支持。

剧透#

可以在文本中添加剧透，文本也支持 Markdown 语法：

1
内容 :spoiler[被隐藏了 **嘿嘿**]！

GitHub 仓库卡片#

可以添加动态卡片来链接到 GitHub 仓库：

1
::github{repo="matsuzaka-yuki/Mizuki"}

3. Mermaid 图表#

本博客支持 Mermaid 图表，可以在文章中创建各种类型的图表。

流程图#

graph TD A[开始] --> B{条件检查} B -->|是| C[处理步骤1] B -->|否| D[处理步骤2] C --> E[结束] D --> E

序列图#

sequenceDiagram participant User participant WebApp participant Server User->>WebApp: 提交请求 WebApp->>Server: 发送数据 Server-->>WebApp: 返回结果 WebApp-->>User: 显示响应

甘特图#

gantt title 项目时间线 dateFormat YYYY-MM-DD section 开发需求分析 :a1, 2023-10-01, 7d 前端开发 :a2, after a1, 15d 后端开发 :a3, after a1, 18d

类图#

classDiagram class User { +String username +String email +login() +logout() } class Article { +String title +String content +publish() +edit() } User "1" -- "*" Article : 撰写

状态图#

stateDiagram-v2 [*] --> 草稿草稿 --> 审核中 : 提交审核中 --> 已发布 : 批准审核中 --> 草稿 : 拒绝已发布 --> 已归档 : 归档已归档 --> [*]

饼图#

pie title 流量来源 "搜索引擎" : 45.6 "直接访问" : 30.1 "社交媒体" : 15.3 "其他来源" : 9.0

4. 嵌入视频#

可以在文章中嵌入来自 YouTube、Bilibili 等平台的视频。

YouTube 视频#

1
<iframe width="100%" height="468"
2
    src="https://www.youtube.com/embed/视频ID"
3
    title="YouTube video player"
4
    frameborder="0"
5
    allowfullscreen>
6
</iframe>

Bilibili 视频#

1
<iframe width="100%" height="468"
2
    src="//player.bilibili.com/player.html?bvid=视频ID&p=1&autoplay=0"
3
    scrolling="no"
4
    border="0"
5
    frameborder="no"
6
    framespacing="0"
7
    allowfullscreen="true">
8
</iframe>

5. 内联 HTML#

对于任何未被 Markdown 语法覆盖的标记，可以直接使用 HTML：

1
<div class="custom-box">
2
    <h3>自定义标题</h3>
3
    <p>这是自定义的 HTML 内容。</p>
4
</div>

6. 自动链接#

Markdown 支持为 URL 和电子邮件地址创建自动链接：

1
<https://example.com/>
2
<address@example.com>

💡 七、进阶技巧#

1. 文章加密#

在文章 frontmatter 中添加：

1
---
2
encrypted: true
3
password: "123456"
4
---

2. 文章置顶#

在文章 frontmatter 中添加：

1
---
2
pinned: true
3
---

3. 文章别名#

在文章 frontmatter 中添加：

1
---
2
alias: "custom-url"
3
---

访问地址变为：/posts/custom-url/

❓ 八、常见问题#

Q1: 文章发布后不显示？#

检查 draft 字段是否设置为 false
检查文件是否在 src/content/posts/ 目录下
尝试刷新浏览器

Q2: 日记不显示？#

检查 id 是否唯一
检查 date 格式是否正确（ISO格式）
确认日记在 diaryData 数组中

Q3: 相册不显示？#

检查 info.json 格式是否正确
本地模式：检查是否有 cover.jpg
外链模式：检查 mode 是否设置为 external
检查 hidden 是否为 false

Q4: 图片不显示？#

确认图片在 public 目录下
检查图片路径是否正确
确认图片格式是否支持

Q5: Mermaid 图表不显示？#

确保使用正确的语法：```mermaid
检查图表代码是否完整
某些复杂图表可能需要等待加载

Q6: 加密文章无法打开？#

确认 encrypted 设置为 true
确认 password 字段已设置
检查密码是否正确

📖 九、更多帮助#

完整文档：https://docs.mizuki.mysqil.com/
Astro 文档：https://docs.astro.build/
GitHub 仓库：https://github.com/matsuzaka-yuki/Mizuki

祝你使用愉快！🎉

博客快速使用指南

https://bk.ltai.top/posts/快速使用指南/

作者

躺平小站

发布于

2026-02-26

许可协议

CC BY-NC-SA 4.0

部分信息可能已经过时

菜谱-蒸菜类合集

Mizuki简单指南