# 简介

前面完成博客框架的搭建和主题配置后，以后就可以专心文章内容的创作了。Hexo 博客需要使用 Markdown 语言编写文章，该语言是一种接近纯文本的轻量级标记型语言，熟悉掌握一些简单的文本标记即可。Hexo 框架的语言引擎会根据文本标记将文本解析成 HTML 语法的网页元素，结合主题样式等配置，就能生成我们所期待的博客网页了。

# Front-matter 前言

Front-matter 是写在文件开头的配置文章信息的 YAML 代码块， 如标题、作者、写作时间和分类等，主要配置字段列表如下：

在文件开头用符号 --- 标识 front-matter 区域，也以符号 --- 结尾。

1
2
3
4
5
6
7
8
9
10

---
title: 文章标题
author: 余年
categroies:
- Hexo
- [个人博客, Hexo]
tags:
- Hexo
- 个人博客
---

以上配置字段在 Hexo 各个主题下基本都支持，而 Shoka 主题提供了其他参数配置，这些配置在其他主题中不一定生效，如文章的置顶、封面贴图等配置。

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27

---
# 文章是否置顶，"true"表示置顶
sticky: true

# 文章首页封面，可配置相对路径或图片外链
# 不配置则从随机图库中抽取作为文章封面显示，或取文章"photos"项第一张图片显示
# cover: https://s2.loli.net/2023/12/16/dzQ23eGm9BCIfjc.jpg
cover: assets/cover-1.jpg

# 文章页面相册，不配置时文章页面顶部会轮播显示随机图库列表中的图片
# 若配置了"photos"项而未配置"cover"项，文章封面贴图取"photos"项配置的第一张图片显示
photos: 
  - assets/photo-1.jpg
  - assets/photo-2.jpg
  - https://api.com/photo-3.jpg
  
# 文章单独的评论设置，"placeholder"项设置评论提示语
valine: 
  placeholder: 请输入你的评论

# 文章单独的背景音乐，将覆盖全局背景音乐
audio:
  - https://music.163.com/song?id=1387098940
  - https://music.163.com/#/playlist?id=2088001742
  - https://www.xiami.com/collect/250830668
  - https://y.qq.com/n/yqq/playsquare/3535982902.html
---

# 标题

Markdown 语言中使用符号 # 标记章节标题。符号 # 的个数对应标题的级别，最多支持六级标题，级别越高字号越小，如下图。符号 # 与标题文本之间需要有一个空格。

# 列表

要点、说明、步骤等需要列举的内容，可以使用列表标签。列表支持无序列表标记并列关系，有序列表标记顺序列表。

无序列表使用 - 、 * 、 + 作为标记符号，三种符号的标记效果相同。次级项需要在标记前加 4 个空格或者一个 Tab制表符 递进。

有序列表使用数字序号，如 1. 、 2. 等等，有序列表通常不支持次级项。

1
2
3
4
5
6
7
8
9
10
11
12

- **无序列表：**

- 第一项
    - 次第一项
    - 次第二项
- 第二项 
- 第三项

**有序列表：**

1. 第一项
2. 第二项

无序列表：

• 第一项
  • 次第一项
  • 次第二项
• 第二项
• 第三项

有序列表：

1. 第一项
2. 第二项

# 超链接

在大多数 markdown 文本编辑器中，直接输入网址会自动转换成链接的形式。如果网址较长或者不想网址直接显示，引用链接在显示时就会更加简洁。

引用链接的格式为 [alt](url "title") ，其中 alt 属性是替代网址显示在正文中的文本， url 配置网址的链接，将鼠标悬停于链接上则会显示 title 属性的文本。其中， alt 和 url 是必须配置的属性， title 属性可不配置，默认为空，即悬停时无显示，但是配置 title 属性时英文双引号不可省略。

1
2

直接输入网址：www.baidu.com
使用[alt](url "title")格式：[百度](www.baidu.com "百度")

效果：
直接输入网址：www.baidu.com
使用 [alt](url "title") 格式： 百度

上述两种方法在编写时依然会在正文中插入网址，链接过多或过长时必然也会影响文章创作时的排版和观感。此时则可以使用网址脚注，将所有网址以脚注的形式罗列在同一处，如文章底部或者段落之间，而在正文中只需要引用脚注即可，而且脚注中的所有网址均不会在网页内容上直接显示，这样就大大减少了网址链接对内容排版的影响。

网址脚注的格式为： [alt]:url "title" ， alt 即、为脚注名， url 和 title 属性则同上。

正文中引用格式为： [站点名称][脚注名] ， 站点名称 为替代脚注名及其对应链接在正文中显示的文本。

网址脚注示例：

1
2
3

脚注引用：[百度][百度]、[Github][Github]
[百度]:www.baidu.com "百度"
[Github]:www.github.com "Github"

脚注引用：百度，Github

# 图片引用

若只在 Typora 此类实时渲染 Markdown 文本的笔记软件上编写博客，引用本地路径的方式插入图片也能获得很好的创作体验。但是浏览博客部署后的网页时，因为图片的相对路径配置容易与部署后的路径冲突，导致无法正常加载图片，所以一般需要使用图片外链以及结合网络图床进行文章图片的引用和管理。

引用本地路径图片与外链图片的格式相同，与超链接引用类似， alt 属性是在图片加载失败时替代图片显示的文本内容， url 属性配置图片的 网络地址 或者 文件路径 ，鼠标悬浮在图片上时显示的则是 title 属性的配置内容。

1

![alt](url "title")

# 表格

表格也是 Markdown 文本中常用的数据格式。表格区域由 列名 、 分割线 和 单元格 三部分组成：

第一行为列名，每列以 | 分隔，表格每行首尾的两个分隔符可以省略；

第二行固定为分割线不能缺少，以符号 - 标记，排版时符号 - 的数量可以多个，而在分割线的两端是否有英文冒号 : 控制着该列的文本对齐方式，冒号 : 在分割线左侧，该列文本将会左对齐，在右侧则是文本右对齐，分割线两端都添加冒号 : 时，文本则是居中对齐，第二行即分割线不会显示在表格内容中；

之后各行则是单元格，可以填入数据或者插入图片等，单元格无内容时，与其他列分隔的 | 不可省略。

示例：

1
2
3
4

| 第一列 | 第二列 | 第三列 |
| :---- | :----: | ----: |
| 数据 | 数据 | 数据 |
| 数据 | 数据 | 数据 |

效果：

Shoka 主题不支持使用换行符 <br /> 在单元格内换行显示，需要在该行的最后添加反斜杠 \ ，在下一行按照表格列数划分单元格，在需要换行的那列对应的单元格内填入内容，这一行的空白单元格就会与上一行合并，就实现了单元格内换行的效果。

1
2
3
4
5
6
7
8

| 第一列 | 第二列 | 第三列 | 第四列 | 第五列 |
| :----: | :----: | :----: | :----: | :----: |
| 数据 | 数据 | 数据 | 数据 | 数据 |\
|  | 数据 |  | 数据 |  |
| 数据 | 数据 | 数据 | 数据 | 数据 |
| 数据 | 数据 | 数据 | 数据 | 数据 |\
|  | 数据 |  | 数据 | |\
|  | 数据 |  |  | 数据 |

注意，表格各行之间不能插入 markdown 注释，否则会破坏表格格式，无法正常显示。

# 代码块

需要插入代码段时，在代码段区域前后使用反引号 ``` 标记起始位置和结束位置，即可生成代码块，符号 ~~~ 也是代码块标记。Shoka 主题内置了 PrimeJS 插件，代码块可以根据语言高亮代码，显示代码行号，并支持配置代码语言、标题、命令行提示等。

代码块支持的参数字段及基本格式为： [language][title][url][link text][mark][command] 。

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23

```java 行高亮 https://shoka.lostyu.me 参考链接 mark:1,6-7
import java.util.Scanner;
...
Scanner in = new Scanner(System.in);
// 输入Scan之后，按下键盘 Alt + “/” 键，Eclipse下自动补全。

System.out.println(in.nextLine());
System.out.println("Hello" + " world.");
```

```bash 命令行提示符 command:("[root@localhost] $":1,9-10||"[admin@remotehost] #":4-6)
pwd
/usr/home/chris/bin
ls -la
total 2
drwxr-xr-x   2 chris  chris     11 Jan 10 16:48 .
drwxr--r-x  45 chris  chris     92 Feb 14 11:10 ..
-rwxr-xr-x   1 chris  chris    444 Aug 25  2013 backup
-rwxr-xr-x   1 chris  chris    642 Jan 17 14:42 deploy
git add -A
git commit -m "update"
git push
```

1
2
3
4
5
6
7

import java.util.Scanner;
...
Scanner in = new Scanner(System.in);
// 输入Scan之后，按下键盘 Alt + “/” 键，Eclipse下自动补全。

System.out.println(in.nextLine());
System.out.println("Hello" + " world.");

1
2
3
4
5
6
7
8
9
10
11

pwd
/usr/home/chris/bin
ls -la
total 2
drwxr-xr-x   2 chris  chris     11 Jan 10 16:48 .
drwxr--r-x  45 chris  chris     92 Feb 14 11:10 ..
-rwxr-xr-x   1 chris  chris    444 Aug 25  2013 backup
-rwxr-xr-x   1 chris  chris    642 Jan 17 14:42 deploy
git add -A
git commit -m "update"
git push

# 文本引用

# 行内引用

在行内引用文本可以让内容更突出，使用一组反引号 ` 标记文本引用，例如：`行内引用` 的显示效果为 行内引用 。

# 整行引用

需要整行强调显示时，在行前添加 > 符号标记，可以添加行的背景效果，并支持嵌套实现多行的分级显示，符号 > 的个数即是嵌套层数。

示例：

1
2
3

> 生如夏花之绚烂，死如秋叶之静美。
>> 出自泰戈尔的《飞鸟集》
>> 泰戈尔是印度诗人

引用效果：

生如夏花之绚烂，死如秋叶之静美。

出自泰戈尔的《飞鸟集》
泰戈尔是印度诗人

# 分割线

在一行内输入 3 个及以上的 * 、 - 或者 _ 符号，即可在此行位置画出一条分割线，注意行内不能有注释或其他内容，不同符号也不能混用。

下方是一条分割线：

# 文字强调

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27

*斜体*或_斜体_
**粗体**
***加粗斜体***
~~删除线~~
==背景高亮==
++下划线++
- 以上是markdown通用语法，下面是主题特殊语法
- 主题风格通用颜色：default、primary(紫色)、success(绿色)、info、warning(黄色)、danger(红色)
++波浪线++{.wavy}
++着重点++{.dot}
++紫色下划线++{.primary}
++绿色波浪线++{.wavy .success}
++黄色着重点++{.dot .warning}
~~红色删除线～～{.danger}
[赤橙黄绿青蓝紫]{.rainbow}
[红色]{.red}
[粉色]{.pink}
[橙色]{.orange}
[黄色]{.yellow}
[绿色]{.green}
[靛青]{.aqua}
[蓝色]{.blue}
[紫色]{.purple}
[灰色]{.grey}
快捷键 [Ctrl]{.kbd} + [C]{.kbd .red}
H~2~0
29^th^

斜体或_斜体_
粗体
加粗斜体
删除线
背景高亮
下划线

• 以上是 markdown 通用语法，下面是主题特殊语法

• 主题风格通用颜色：default、primary (紫色)、success (绿色)、info、warning (黄色)、danger (红色)

波浪线
着重点
紫色下划线
绿色波浪线
黄色着重点
～～红色删除线～～{.danger}
赤橙黄绿青蓝紫
红色
粉色
橙色
黄色
绿色
靛青
蓝色
紫色
灰色
快捷键 Ctrl + C
H₂0
29^th

# 特殊字符

因为一些特殊字符作为 Markdown 语法的标记，无法直接输入显示，此时需要用反斜杠 / 先将字符转义，或者使用其字符实体编码，才能避免字符解析时被识别成标记。

字符实体的半角分号 ; 不可省略，以下是一些常用字符的字符实体：

# Shoka 特殊功能

# Emoji 表情

Shoka 主题支持 emoji 表情列表中的所有文字表情，行内直接使用即可。

1
2
3
4

- emoji标签使用
:kissing_heart:
:ring:
:notes:

# 文字隐藏

某些内容不想直接显示，可以将文字掩盖住，只有鼠标滑过或者选中掩盖区域的文字时才会显示，使用格式如下：

1
2
3

# 标签尾部的!会被渲染成中文也就是全角符号，标签其实前后的!都是英文半角符号
!! 黑幕黑幕黑幕黑幕黑幕黑幕 !!: 鼠标滑过显示内容
!! 模糊模糊模糊模糊模糊模糊 !! {.bulr} : 选中文字显示内容

黑幕黑幕黑幕黑幕黑幕黑幕 ： 鼠标滑过显示内容

模糊模糊模糊模糊模糊模糊 {.bulr} ： 选中文字显示内容

# 链接卡片

将链接以卡片的形式显示，更加方便链接的排版和管理，只需依照配置格式填入链接的字段信息就可以使用链接卡片功能。

links 标签可配置的字段：

配置格式如下：

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16

{% links %}
- site: 優萌初華
  owner: 霜月琉璃
  url: https://shoka.lostyu.me
  desc: 琉璃的医学 & 编程笔记
  image: https://cdn.jsdelivr.net/gh/amehime/shoka@latest/images/avatar.jpg
  color: "#e9546b"
- site: 優萌初華
  owner: 霜月琉璃
  url: https://shoka.lostyu.me
  image: images/avatar.jpg
- site: 優萌初華
  url: https://shoka.lostyu.me
  desc: 琉璃的医学 & 编程笔记
  color: "#9d5b8b"
{% endlinks %}

创作时如配置大量 links 链接块会极大影响篇幅和排版，此时用文件来保存显示在同一处的链接卡片，而文章中只需使用 linksfile 标签引用对应文件导入所有的链接块即可。链接块的信息需要保存在 .yml 文件中， linksfile 标签引用文件的相对路径，起始根目录为 source 目录，所以 yml 文件也要放在 source 目录及其子目录下。

1
2

格式：{% linksfile [path] %}
{% linksfile friends/data.yml %}

链接在文件中配置的顺序就是卡片在文章中显示的顺序。

# Label 标签

行内某些特殊内容需要强调时，虽然可以使用反引号引用的形式，不过 Label标签 具有更多样式的强调效果。

1
2
3
4
5
6

[default]{.label}
[primary]{.label .primary}
[info]{.label .info}
[:heavy_check_mark:success]{.label .success}
[warning]{.label .warning}
[:broken_heart:danger]{.label .danger}

default
primary
info
✔️success
warning
💔danger

# Note 提醒块

Note提醒块 的效果类似于前面说的整行引用，不过增加了提示图标。

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27

:::default
默认默认
:::

:::primary
基本基本
:::

:::info
提示提示
:::

:::success
成功成功
:::

:::warning
警告警告
:::

:::danger
危险危险
:::

:::danger no-icon
危险危险
:::

# Tab 标签块

Tab标签块 通过点击切换实现同一行中显示不同内容，可以嵌套链接卡片、提示块等，并且只有切换后其他块的样式才会显示。

使用格式：

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36

;;;[tabID] [标签名称] # 开始行
[内容] # 标签卡片显示的内容
;;; # 结束行
# 注意：
# 每个卡片都需要一个完整标签块
# 同一行显示的不同卡片其对应的tabID需要相同；

;;;id1 卡片 1
这里是卡片 1 的内容
**加粗**
[success]{.label .success}
{% links %}
- site: 優萌初華
  owner: 霜月琉璃
  url: https://shoka.lostyu.me
  desc: 琉璃的医学 & 编程笔记
  image: https://cdn.jsdelivr.net/gh/amehime/shoka@latest/images/avatar.jpg
  color: "#e9546b"
{% endlinks %}
;;;

;;;id1 卡片 2
这里是卡片 2 的内容
:::danger
危险危险
:::
- 第一行
- 第二行
;;;

;;;id2 ②号标签卡片 1
这里是卡片 1 的内容
;;;
;;;id2 ②号标签卡片 2
这里是卡片 2 的内容
;;;

# Collapse 折叠块

折叠块可以将较长的内容折叠，，可以有效减少网页显示的篇幅，便于浏览主要内容。

1
2
3
4

# 使用+++标记折叠块
+++[风格颜色] [标题文字] # 开始行
[内容] # 折叠块内容，可以内嵌其他块标签内容
+++ # 结束行

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37

+++ 默认默认 这里是一段文字
++下划线++
+++

+++primary 紫色
:::info
参考信息
:::
- 第一行
- 第二行
+++

+++info  蓝色
;;;id3 卡片 1
这里是卡片 1 的内容
;;;
;;;id3 卡片 2
这里是卡片 2 的内容
;;;
+++

+++success 绿色
{% links %}
- site: 優萌初華
  url: https://shoka.lostyu.me
  color: "#e9546b"
{% endlinks %}
+++

+++warning 黄色
!!警告警告警告警告警告!!{.bulr}
[label]{.label .success}
+++

+++danger 红色
[danger]{.label .danger}
+++

# TaskList 待办事项

待办事项的风格颜色时需要在标签行下另起两行配置，颜色只对 [x] 标记后的选项生效，不配置或者无标记均显示默认颜色，。

1
2
3
4
5
6
7

- [ ] 这是一个小叉叉
- [x] 这是一个红色勾勾

{.danger}

- [ ] 未完成
- [x] 默认颜色

• 这是一个小叉叉
• 这是一个红色勾勾

• 未完成
• 默认颜色

# 结语

本篇介绍的内容基于 Markdown 通用语法、Hexo 官方文档及 Shoka 主题文档等，介绍的也都是常用的标签，有一部分 Shoka 主题支持的功能如多媒体配置、数学公式和流程图等，因为调试渲染时存在问题，未在本文内容涉及，可以自行查看主题作者的文档和示例代码。