用 Markdown 写博客：写作指南

三十秒上手

在 docs/blog/ 目录下新建一个 .md 文件，写上标题和日期，然后开始写正文：

---
title: 我的新文章
date: 2026-10-23
category: 博客
tags: [随笔]
---

正文从这里开始，正常用 Markdown 写就行。

保存，首页、全部文章、时间归档、标签索引这四个页面会自动出现这篇文章——不需要注册、不需要改配置。

TIP

文件名前缀不影响排序，排序只看 frontmatter 里的 date。

frontmatter 字段

字段	类型	必填	说明
title	string	否	文章标题。不写的话会自动取正文第一个 # 标题
date	string	是	发布日期，如 2026-10-23。没有这个字段的页面不会被当成文章
category	string	否	分类，默认 未分类
tags	array / string	否	标签，写 [A, B] 或 A,B 都行
excerpt	string	否	摘要。不写会自动截取正文第一段
cover	string	否	封面图
sticky	number	否	置顶权重，数字越大越靠前，会出现在首页「置顶精选」里
layout	string	否	填 CategoryPage 时该页变成「分类导航页」，不计入文章列表

封面图怎么挂

两种方式：

1. 放在 docs/public/covers/ 下，frontmatter 里写绝对路径：

   cover: /covers/hello-world.svg

2. 放在文章同目录的 assets/ 下，frontmatter 里写相对路径：

   cover: ./assets/screenshot.png

第二种方式图片会被 Vite 处理并加上 hash，文件名带中文或特殊字符都没问题。

WARNING

frontmatter 里的相对路径不会像正文里的 ![]() 那样被自动处理。写错了不会报错，只会显示成一块纯色渐变占位。

正文里能写什么

标准 Markdown 全都支持，另外还有这些增强：

::: info
这是提示框，也可以用 tip / warning / danger。
:::

::: details
点开才显示的内容
:::

- [ ] 待办事项
- [x] 已完成的任务

`行内代码`、```代码块```、表格、引用、折叠，都好使。

代码块支持语法高亮：

def hello():
    print("你好，xsinfo")

常见问题

文章没出现在首页？ 检查 frontmatter 里有没有 date 字段，没有的话会被当成普通文档页忽略。

想给某篇文章置顶？ 加一行 sticky: 1，数字越大越靠前。

想新建一个分类页？ 新建一个 .md，写上 layout: CategoryPage 和 category: 你的分类名，页面会自动列出该分类下的所有文章。

怎么改配色和样式？ 全部在 docs/.vitepress/theme/styles/ 下面。vars.css 是唯一的配色入口（浅色 + 深色两套令牌），motion.css 放装饰元素与动效，home.css / blog.css / post.css 分别是首页、列表页、文章页的样式，base.css 是全站通用样式。改颜色只动 vars.css 就行。

---

写文章就是写 Markdown，剩下的交给站点。有问题随时来问。