Markdown 编写教程 - Ksayus の猫窝

本文是 Ksayus の猫窝的 Markdown 编写完全指南，涵盖从基础语法到 Firefly 主题扩展功能的全部用法。无论你是 Markdown 新手还是老手，都能在这里找到实用的写法。

目录#

文章结构
基础语法
- 标题
- 段落与换行
- 文本样式
- 列表
- 引用
- 链接
- 图片
- 代码
- 表格
- 分割线
Firefly 扩展语法

文章结构#

每篇文章由 Frontmatter（元数据）和正文两部分组成。Frontmatter 位于文件顶部，用 --- 包裹：

1
---
2
title: 文章标题
3
published: 2024-01-01
4
description: 文章摘要，用于 SEO 和列表预览
5
image: ./cover.jpg
6
tags: [标签1, 标签2]
7
category: 分类名
8
draft: false
9
pinned: false
10
comment: true
11
---

常用字段说明#

字段	必填	说明
`title`	✅	文章标题
`published`	✅	发布日期，格式 `YYYY-MM-DD`
`description`	推荐	文章摘要，显示在列表和 SEO 中
`image`	可选	封面图，支持相对路径、`/` 开头的 public 路径或远程 URL
`tags`	可选	标签数组
`category`	可选	分类
`draft`	可选	`true` 时为草稿，不会发布
`pinned`	可选	`true` 时置顶
`comment`	可选	是否允许评论，默认 `true`
`slug`	可选	自定义 URL 路径
`series`	可选	系列名称，同系列文章会自动关联

Tip

使用 pnpm new-post 文章名 命令可以快速创建带模板的文章文件。

基础语法#

标题#

使用 # 表示标题，1~~6 个 # 对应 h1~~h6：

1
# 一级标题
2
## 二级标题
3
### 三级标题
4
#### 四级标题
5
##### 五级标题
6
###### 六级标题

Note

文章正文建议从 ## 开始，因为 # 一级标题已由文章标题占用。

段落与换行#

段落之间用空行分隔。行尾加两个空格实现强制换行：

1
这是第一段。
2

3
这是第二段。
4

5
行尾两个空格
6
实现换行。

文本样式#

1
**粗体**
2
*斜体*
3
***粗斜体***
4
~~删除线~~
5
`行内代码`

粗体 · 斜体 · 粗斜体 · ~~删除线~~ · 行内代码

列表#

无序列表：使用 -、* 或 +

1
- 项目一
2
- 项目二
3
  - 嵌套项目
4
  - 嵌套项目二

有序列表：使用数字加 .

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

任务列表：

1
- [x] 已完成的任务
2
- [ ] 未完成的任务
3
- [ ] 另一个任务

引用#

使用 > 表示引用，支持嵌套：

1
> 这是一段引用。
2
>
3
> > 这是嵌套引用。

这是一段引用。
这是嵌套引用。

链接#

1
[显示文本](https://example.com)
2
[带标题的链接](https://example.com "鼠标悬停提示")
3
<https://example.com>

图片#

1
![替代文本](./images/example.jpg)
2
![带标题](https://example.com/img.png "图片标题")

图片路径支持三种格式：

./images/xxx.jpg — 相对文章文件的路径
/assets/images/xxx.jpg — public 目录下的绝对路径
https://... — 远程 URL

代码#

行内代码：用反引号包裹

1
使用 `console.log()` 输出信息

代码块：用三个反引号包裹，可指定语言

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

表格#

1
| 左对齐 | 居中 | 右对齐 |
2
|:------|:----:|------:|
3
| 内容1 | 内容2 | 内容3 |
4
| 内容4 | 内容5 | 内容6 |

左对齐	居中	右对齐
内容1	内容2	内容3
内容4	内容5	内容6

分割线#

1
---
2
***
3
___

Firefly 扩展语法#

提醒块 Callouts#

Firefly 支持四种风格的提醒块，可在 siteConfig.ts 中切换主题。本站使用 GitHub 风格，语法如下：

1
> [!NOTE]
2
> 提示信息，用户应该注意的内容。
3

4
> [!TIP]
5
> 实用技巧或建议。
6

7
> [!IMPORTANT]
8
> 关键信息，必须了解的内容。
9

10
> [!WARNING]
11
> 警告，需要立即注意。
12

13
> [!CAUTION]
14
> 注意，可能产生负面后果。

Note

提示信息，用户应该注意的内容。

Tip

实用技巧或建议。

Important

关键信息，必须了解的内容。

Warning

警告，需要立即注意。

Caution

注意，可能产生负面后果。

也支持自定义标题：

1
> [!NOTE] 自定义标题
2
> 这是一个带有自定义标题的提示框。

自定义标题

这是一个带有自定义标题的提示框。

GitHub 仓库卡片#

一行代码即可展示 GitHub 仓库信息卡片：

1
::github{repo="CuteLeaf/Firefly"}

CuteLeaf

Firefly

🍀Firefly, fresh and aesthetic Astro blog theme template.

—

MIT

Astro

增强代码块#

本站基于 Expressive Code 提供强大的代码块增强功能。

语法高亮与语言标识#

1
```typescript
2
const message: string = "Hello, TypeScript!";
3
console.log(message);
4
```

标题与框架#

为代码块添加文件名标题，自动渲染为编辑器样式：

1
```js title="hello.js"
2
console.log("带标题的代码块");
3
```

终端命令自动渲染为终端样式：

1
```bash
2
pnpm install
3
pnpm dev
4
```

行标记#

高亮特定行或行范围：

1
```js {1, 3-4}
2
const a = 1;      // 高亮
3
const b = 2;
4
const c = a + b;  // 高亮
5
console.log(c);   // 高亮
6
```

行号#

1
```js showLineNumbers
2
console.log("显示行号");
3
console.log("第2行");
4
```

也可自定义起始行号：showLineNumbers startLineNumber=10

可折叠代码#

长代码可以折叠部分行：

1
```js collapse={1-4}
2
// 这些行会被折叠
3
import { foo } from "bar";
4
import { baz } from "qux";
5

6
// 这行可见
7
console.log("Hello");
8
```

Tab 代码组#

多个代码块合并为标签页：

1
::: code-group labels=[JavaScript, Python]
2

3
```js
4
console.log("Hello");
5
```
6

7
```py
8
print("Hello")
9
```
10

11
:::

图片网格#

使用 [grid] 标签将多张图片并排展示，自动响应式布局：

1
[grid]
2
![图1](./images/1.jpg)
3
![图2](./images/2.jpg)
4
![图3](./images/3.jpg)
5
[/grid]

Note

同一排中高度不同的图片会自动裁剪对齐，点击可查看原图。

剧透文本#

使用 :spoiler[] 包裹需要隐藏的内容：

1
这是剧透：:spoiler[真相只有一个！]

这是剧透：真相只有一个！

Wiki 内部链接#

支持 Obsidian 风格的 [[ ]] 内部链接，链接到本站其他文章。

文章卡片（单独成段时渲染为卡片）：

1
[[markdown-extended]]

行内链接：

1
请参阅 [[markdown-extended|Markdown 扩展功能]] 了解更多。

链接目标支持三种写法：

[[slug]] — 文章的 slug
[[guide/firefly-wiki-link]] — 文件相对路径
[[firefly-wiki-link]] — 裸文件名（唯一时）

Mermaid 图表#

在代码块中使用 mermaid 语言绘制流程图、时序图等：

1
```mermaid
2
graph TD
3
    A[开始] --> B{是否登录?}
4
    B -->|是| C[进入主页]
5
    B -->|否| D[跳转登录页]
6
```

PlantUML 图表#

使用 plantuml 语言绘制 UML 图：

1
```plantuml
2
@startuml
3
Alice -> Bob: Hello
4
Bob --> Alice: Hi!
5
@enduml
6
```

KaTeX 数学公式#

行内公式：用 $ 包裹

1
质能方程 $E = mc^2$ 是物理学的基础。

块级公式：用 $$ 包裹

1
$$
2
\int_{-\infty}^{\infty} e^{-x^2} dx = \sqrt{\pi}
3
$$

\int_{-\infty}^{\infty} e^{-x^2} dx = \sqrt{\pi}

写在最后#

以上就是本站支持的全部 Markdown 语法。建议结合 Markdown 扩展功能和代码块示例两篇文章一起阅读，获得更完整的示例。

祝写作愉快！🐱

音乐

音乐

目录#

文章结构#

常用字段说明#

基础语法#

标题#

段落与换行#

文本样式#

列表#

引用#

链接#

图片#

代码#

表格#

分割线#

Firefly 扩展语法#

提醒块 Callouts#

GitHub 仓库卡片#

增强代码块#

语法高亮与语言标识#

标题与框架#

行标记#

行号#

可折叠代码#

Tab 代码组#

图片网格#

剧透文本#

Wiki 内部链接#

Mermaid 图表#

PlantUML 图表#

KaTeX 数学公式#

写在最后#

支持与分享