文章

markdown技巧

markdown语法间接高效，结合vim和obsidian.nvim的高效编辑，可以快速的进行创作。用了 `markdown+vim+obsidian.nvim`组合工具链之后，我敢肯定你是回不去 `obsidian app` 了。配合 jekyll 静态博客工具，可以轻易的把自己的文档发布到 gitpage 或其他支持静态网页的平台。知识输入输出就高效闭环了。

发表于
作者 Jacky
15 分钟阅读
markdown技巧

obsidian 特有语法

双向链接 [[]]

标准 Markdown 链接格式：[显示文本](文件路径.md) Obsidian 特有：Wiki 双向链接

特点：自动生成反向链接、图谱；不需要写完整文件路径。

1
2
3
4

[[笔记名称]]                     # 链接到库内笔记
[[笔记名称#标题]]                # 跳转到另一笔记指定标题
[[笔记名称#^block-id]]         # 跳转到另一笔记指定块
[[笔记名称|自定义显示文字]]      # 别名，管道符 |

块嵌入 ![[]]

标准 Markdown：只能插入图片 ![alt](url)，不能嵌入整篇文档片段。 Obsidian 特有嵌入语法，把其他笔记 / 图片 / PDF 直接渲染到当前页面：

1
2
3
4
5
6

![[另一个笔记.md]]                # 嵌入整篇笔记
![[另一个笔记#标题]]              # 只嵌入某一个标题下内容
![[另一个笔记#^block-id]]         # 只嵌入单个块
![[图片.png]]                # 库内图片嵌入
![[图片.png|300]]                 # 限定图片宽度300px（|管道）
![[文档.pdf#page=5]]              # 嵌入PDF指定页面

块id 和块引用

标准 Markdown没有块级锚点，只能锚标题。

1
2
3
4

这一段内容 ^myid                   # 定义块ID，前面要有空格

[[当前笔记#^myid]]                 # 链接到此块
![[当前笔记#^myid]]                # 嵌入这个单独块

^xxx 写在段落末尾，代表给这个文本块分配唯一标识，实现精确块跳转 / 嵌入。

高亮文本 ==内容==

标准 Markdown 没有文本高亮语法（GFM 也没有）。

Callout 提示框 > [!type]

1
2
3
4
5
6
7
8
9
10
11

> [!note] 笔记标题
> 备注内容

> [!warning] 警告
> 警告信息

> [!tip]- 默认折叠
> 内容默认收起，点击展开

> [!info]+ 默认展开
> 默认展开状态

支持类型：note/tip/warning/danger/info/question/todo/success/bug等。

注释语法 %% 注释 %%

标准 Markdown 没有原生注释。 Obsidian 注释在阅读视图隐藏，编辑视图可见，不会输出到渲染结果。

1
2
3
4
5
6

可见文字 %%这里是隐藏注释%% 继续可见文字

%%
多行注释
全部隐藏
%%

内部标签语法 #tag

注意：普通 Markdown 里#只代表标题； Obsidian 中#后面不带空格识别为标签，可检索、标签面板筛选，支持层级标签#项目/待办

1

#工作 #笔记/技术学习

Frontmatter 属性（YAML 头部）

1
2
3
4
5
6

---
tags: [工作,阅读]
aliases: ["别名1","别名2"]
cssclass: my-note
---
正文内容

Obsidian 增强的图片管道语法 |

标准 markdown 图片 ![alt](xxx.png)，alt 是替代文本，不能控制尺寸。 Obsidian wikilink 图片用管道控制大小：

1
2

![[pic.jpg|400]]      # 宽400px
![[pic.jpg|400x200]]  # 宽x高

chirpy 主题特有语法

【注意】： 不要使用一级标题，因为一级标题不会出现在右边的目录里。最好从二级目录开始。

独有的提示框 Prompt（Callout）

Obsidian 用> [!tip]； Chirpy 不支持 [!xxx]，使用 kramdown IAL 属性 {: .prompt‑xxx}。

1
2
3
4
5
6
7
8
9
10
11

> 这是提示内容
{: .prompt-tip }

> 信息提示
{: .prompt-info }

> 警告提示
{: .prompt-warning }

> 危险/错误提示
{: .prompt-danger }

支持 4 种：.prompt-tip / .prompt-info / .prompt-warning / .prompt-danger。

注意： {: ...} 必须紧跟引用块，中间不能有空行。标准 Markdown 没有 IAL 属性语法。

行内样式类（IAL 属性语法，kramdown，Chirpy 直接生效）

IAL {: .class} 是 kramdown 扩展，不属于 CommonMark/GFM，Chirpy 大量使用。

文件路径高亮 .filepath

1

`/etc/nginx/conf.d`{: .filepath}

渲染为灰色文件路径样式，普通 Markdown 只会渲染普通行内代码。

代码块关闭行号 .nolineno

1

echo "无行号"

如果里面有文件名，还可以同时用 {: .filepath}

图片加类、设置宽高（kramdown IAL）

注意：使用 .left / .right 浮动时，不要写图片 alt 标题，否则布局异常。

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

# 博客文章主题
---
image:
  path: /path/to/image
  alt: image alternative text
---

![图片标准md写法](/assets/img/demo.png)
![图片描述](assets/img/demo.png){: width="400" }
![图片](assets/img/demo.png){: .shadow }

# 设置宽高，两种写法等价
![Desktop View](/assets/img/sample/mockup.png){: width="700" height="400" }
![Desktop View](/assets/img/sample/mockup.png){: w="700" h="400" }

# 窗口截图增加阴影（Chirpy内置 .shadow）
![screenshot](/assets/img/screen.png){: .shadow }

# 对齐方式
![pic](/assets/img/a.png){: .normal }   # 左对齐（取消默认居中）
![pic](/assets/img/a.png){: .left }     # 向左浮动，文字环绕右侧
![pic](/assets/img/a.png){: .right }    # 向右浮动，文字环绕左侧

![这是图片下方显示的图注文字](/assets/img/demo.png){: w="500" }

![图片标准md写法](/assets/img/demo.png)
*这是图片下方标题*

![img-description](/path/to/image)
_这也是图片下方标题_

# 图片套超链接（点击图片跳转网页）
[![图注](/assets/img/demo.png){: .shadow }](https://example.com)

用代码画的图片，可以直接用代码画：

  • Mathematics 公式
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

<!-- Block math, keep all blank lines -->

$$
LaTeX_math_expression
$$

<!-- Equation numbering, keep all blank lines  -->

$$
\begin{equation}
  LaTeX_math_expression
  \label{eq:label_name}
\end{equation}
$$

Can be referenced as \eqref{eq:label_name}.

<!-- Inline math in lines, NO blank lines -->

"Lorem ipsum dolor sit amet, $$ LaTeX_math_expression $$ consectetur adipiscing elit."

<!-- Inline math in lists, escape the first `$` -->

1. \$$ LaTeX_math_expression $$
2. \$$ LaTeX_math_expression $$
3. \$$ LaTeX_math_expression $$
  • plantUML

可以用在线plantUML的svg或其他格式的图URL，也可以借助插件直接写plantUML代码。

  • Mermaid 工具

需要开启以下属性：

1
2
3

---
mermaid: true
---

音频/视频/PDF

  • 本地或其他平台视频：本地文件放 /assets/videos/，其他平台直接在 src 中填视频 URL
1
2
3
4
5
6
7
8
9

{% include embed/video.html
src="/assets/videos/demo.mp4"
title="视频标题（下方显示）"
poster="/assets/img/video-cover.jpg"
autoplay=false
loop=false
muted=true
types="mp4|webm"
%}
  • 平台音频或视频：Platform 目前支持 youtube, twich, bilibili, spotify
1
2
3

{% raw %}
{% include embed/{Platform}.html id='{ID}' %}
{% endraw %}
  • 音频
1
2
3
4
5
6
7
8

{% raw %}
{%
  include embed/audio.html
  src='/path/to/audio.mp3'
  types='ogg|wav|aac'
  title='Demo audio'
%}
{% endraw %}
  • PDF: Chirpy 没有内置组件，用 HTML
1

<iframe src="/assets/file/doc.pdf" width="100%" height="600"></iframe>

网页超链接

  • 标准写法：
1
2

[显示文字](https://example.com)          # 外部网页
[跳转到本站另一篇文章](/posts/my-article/) # 站内相对链接
  • 特有写法：
1
2
3
4

[外部网站](https://example.com){:target="_blank"}

# 同时加rel安全属性
[外部网站](https://example.com){:target="_blank" rel="noopener noreferrer"}
  • Jekyll {% link %} Liquid 标签（推荐站内资源，自动补全 baseurl）

当你的站点配置了baseurl，直接写路径容易出错，使用{% link %}会自动拼接 baseurl： liquid

1
2
3
4

{% raw %}
[文章示例]({% link _posts/2026‑08‑01‑test.md %})
[图片]({% link /assets/img/demo.png %})
{% endraw %}

站内链接

  • 页内锚点（跳转到本页标题）

kramdown 自动把标题转成 id，中文标题会做转码；简单写法：

1
2
3

[跳转到第二节](#第二节)

## 第二节

自定义锚 ID：

1
2
3

## 章节标题 {#custom‑id}

[跳转到此](#custom‑id)

跳转到其他文章的标题（跨文章锚点）

1
2
3

{% raw %}
[另一篇文章的小节]({% link _posts/2026‑08‑01‑other.md %}#custom‑id)
{% endraw %}

Front‑Matter Chirpy 专属字段（文章头部 YAML）

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

---
title: 文章标题
date: 2026‑08‑20 10:00:00 +0800

# ↓ Chirpy专属
pin: true               # 文章置顶 true/false
toc: true               # 是否开启目录
comments: true          # 是否开启评论
math: true              # 开启LaTeX数学公式渲染
mermaid: true           # 开启Mermaid图表渲染
excerpt: "摘要文字"      # 自定义摘要，不写自动截取
description: "SEO描述"
image: /assets/img/cover.jpg # 文章封面图，用于社交分享
---

kramdown 自带扩展（Chirpy 开箱支持，但不属于标准 Markdown）

描述列表

1
2
3
4
5
6

关键词
: 这是关键词的描述

Chirpy
: Jekyll技术博客主题

块 ID、自定义属性（IAL）

可做页面内锚点跳转，标准 Markdown 不支持。

1
2
3
4

## 章节标题 {#my‑section}

一段文字
{: #block‑id .red }

脚注（kramdown 增强）

1
2
3

这里有脚注[^note1]

[^note1]: 脚注内容，可以有多行。

基本markdown语法

分类语法示例渲染效果说明
标题 H1# 一级标题一级大标题
标题 H2## 二级标题二级标题
标题 H3### 三级标题三级标题
标题 H4#### 四级标题四级标题
标题 H5##### 五级标题五级标题
标题 H6###### 六级标题六级标题
H1 底线写法标题文字\n=====等价一级标题
H2 底线写法标题文字\n-----等价二级标题
段落普通文本一行。\n\n新段落。空一行分隔段落
软换行第一行末尾两个空格 \n第二行不产生新段落，仅换行
粗体**粗体文字**文字加粗
斜体*斜体文字*文字倾斜
粗斜体***粗斜体***同时加粗倾斜
删除线(GFM)~~删除文字~~文字中间划线
无序列表 -- 列表项无序列表，减号开头
无序列表 ** 列表项无序列表，星号开头
无序列表 ++ 列表项无序列表，加号开头
有序列表1. 第一项\n2. 第二项数字+英文句点
嵌套列表- 一级\n - 二级2空格缩进实现嵌套
引用块> 引用内容块引用
多行引用> 第一行\n> 第二行多行引用块
行内代码`code`行内等宽代码
代码块(反引号)\npython\nprint(“hello”)\n\n围栏代码块，可指定语言
缩进代码块` 4空格缩进代码`4空格缩进构成代码块
超链接[链接文字](https://example.com)行内链接
带标题链接[链接文字](https://xxx "标题")鼠标悬浮显示title
引用式链接[文字][id]\n[id]: https://url复用链接地址
图片![替代文本](https://xxx.jpg)插入网络图片
图片带title![alt](url.jpg "图片标题")图片悬浮提示
表格(GFM)\|A\|B\|\n|---|---|\n\|1\|2\|简单表格，分隔行必须有短横线
任务列表(GFM)- [ ] 未完成\n- [x] 已完成复选框任务列表，x大小写均可
水平分割线---水平分隔线，单独一行
水平分割线***水平分隔线，单独一行
脚注(GFM)文字[^1]\n[^1]:脚注内容页面底部生成脚注
转义字符\*反斜杠转义特殊符号，输出原符号

表格对齐

左对齐居中对齐右对齐
内容1内容2内容3
高效工具
Tool
本文由作者按照 CC BY 4.0 进行授权

热门标签

Tool Vim