lil_DengZi's Notes

markdown学习

Properties2
tagsmarkdown, obsidian, 文档规范
aliasesMarkdown 学习, Markdown 使用说明

13分钟阅读

Markdown 学习

本文是一份 Markdown 与 Obsidian 常用写法说明书，适合用于笔记、项目文档、README、技术方案和知识库页面。

目录

Markdown 是什么

Markdown 是一种轻量级标记语言，用纯文本表达标题、列表、链接、图片、代码块、表格等结构。它的目标不是做复杂排版，而是让内容结构清楚、易读、易维护。

常见使用场景：

  • 个人知识库：学习笔记、阅读记录、问题复盘。
  • 项目文档：README、接口说明、部署说明、变更记录。
  • 技术写作：教程、排错指南、设计方案。
  • 协作材料：会议纪要、需求说明、任务清单。

基础语法

标题

标题使用 # 表示层级，# 后面必须加一个空格。

# 一级标题
## 二级标题
### 三级标题
#### 四级标题
##### 五级标题
###### 六级标题

使用建议：

  • 每篇文档只保留一个一级标题。
  • 标题层级不要跳跃，例如不要从 ## 直接跳到 ####。
  • 标题写清主题，不写成“说明”“其他”“补充”这类含糊词。

段落与换行

普通文本直接书写即可。段落之间使用一个空行分隔。

这是第一段。
 
这是第二段。

如果必须在同一段内强制换行，可以在行尾输入两个空格，或使用 <br>。一般文档中优先使用空行分段，不滥用 <br>。

强调

*斜体*
**加粗**
***加粗斜体***
~~删除线~~
`行内代码`

效果示例：

斜体

加粗

加粗斜体

删除线

行内代码

使用建议：

  • 加粗用于强调关键结论、字段名、注意事项。
  • 行内代码用于命令、路径、变量、函数、配置项，例如 npm run dev、README.md、PORT。
  • 不建议用大量颜色、下划线和 HTML 字体标签制造视觉效果，技术文档应优先保持一致性。

列表

无序列表：

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

有序列表：

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

嵌套列表使用两个或四个空格缩进，保持同一篇文档内一致。

- 项目文档
  - README
  - 部署说明
  - 接口说明

使用建议：

  • 有顺序的流程使用有序列表。
  • 无先后关系的要点使用无序列表。
  • 列表项尽量保持同类表达，例如都用名词短语，或都用动宾短语。

引用

引用使用 >。

> 这是一段引用内容。

多层引用：

> 外层引用
>
> > 内层引用

使用建议：

  • 引用适合放原文、定义、规范条款、提示说明。
  • 不要把正文大段内容都写成引用，避免结构失焦。

分割线

使用三个或更多 -、*、_ 可生成分割线。

---

使用建议：分割线只用于明显分隔不同区域，不要用它替代标题层级。

链接

普通链接：

[显示文字](https://example.com)

自动链接：

<https://example.com>

文档内锚点链接：

[跳转到代码块](#代码块)

引用式链接，适合长链接集中管理：

参考 [Markdown Guide][markdown-guide]。
 
[markdown-guide]: https://www.markdownguide.org/

Obsidian 双链

Obsidian 使用 [[页面名]] 连接笔记，适合建立知识网络。

链接到页面

[[文档编写基础知识]]
[[Latex自查表]]

当页面不存在时，点击双链可以创建新页面。

链接到标题

[[文档编写基础知识#标题层级]]

适合从一篇笔记精确跳到另一篇笔记的某个章节。

链接并显示别名

[[文档编写基础知识|文档写作说明书]]

渲染时显示为“文档写作说明书”，实际链接仍指向 文档编写基础知识。

嵌入其他笔记

![[文档编写基础知识]]

嵌入适合复用固定说明、检查清单、公式表等内容。不要滥用嵌入，否则一篇文档会变得难以维护。

Obsidian 常用 frontmatter

---
tags:
  - Markdown
  - 文档规范
aliases:
  - Markdown 使用说明
created: 2026-05-20
---

说明：

  • tags 用于分类检索。
  • aliases 用于设置别名。
  • created、updated 可用于记录时间。

代码块

行内代码

使用反引号包裹短代码、命令、路径、字段名。

运行 `npm install` 安装依赖。
配置文件位于 `config/app.yml`。

多行代码块

使用三个反引号包裹，并建议标明语言。

```python
def hello(name: str) -> str:
    return f"Hello, {name}"
```

常见语言标识：

场景语言标识
Shell 命令bash、shell、powershell
Pythonpython
JavaScriptjavascript、js
TypeScripttypescript、ts
JSONjson
YAMLyaml
Markdownmarkdown
SQLsql

命令示例写法

npm install
npm run dev

说明命令时应写清：

  • 在哪个目录运行。
  • 命令做什么。
  • 成功后会看到什么。
  • 常见失败原因是什么。

配置示例写法

server:
  port: 8080
  host: 127.0.0.1

配置文档要说明字段含义、默认值、是否必填、取值范围。

表格

基础表格：

| 字段 | 类型 | 必填 | 说明 |
| --- | --- | --- | --- |
| name | string | 是 | 用户名 |
| age | number | 否 | 年龄 |

效果：

字段类型必填说明
namestring是用户名
agenumber否年龄

对齐方式：

| 左对齐 | 居中 | 右对齐 |
| :--- | :---: | ---: |
| A | B | C |

使用建议：

  • 表格适合比较结构化信息，例如参数、字段、版本差异。
  • 单元格内容不要太长，长说明应移到表格下方。
  • 表头名称要具体，例如“默认值”比“备注”更清楚。

图片与附件

普通图片

![图片说明](./images/example.png)

Obsidian 附件嵌入

![[example.png]]

控制图片显示尺寸

Obsidian 常见写法：

![[example.png|600]]

HTML 写法：

<img src="./images/example.png" alt="图片说明" width="600">

使用建议：

  • 图片必须有说明，方便读者理解图片目的。
  • 截图前隐藏无关窗口和隐私信息。
  • 项目文档中的图片建议放在固定目录，例如 assets/ 或 images/。
  • 图片文件名使用英文、数字和短横线，例如 login-flow.png。

任务列表

Markdown 任务列表：

- [ ] 未完成任务
- [x] 已完成任务

示例：

  • 补充部署说明
  • 完成 README 初稿

Obsidian 中任务列表适合做轻量待办，但如果任务有负责人、截止时间、状态流转，建议使用专门的项目管理工具或表格。

脚注、注释与转义

脚注

这里有一条脚注。[^note]
 
[^note]: 这是脚注内容。

HTML 注释

<!-- 这段内容不会在预览中显示 -->

转义字符

当需要显示 Markdown 特殊符号本身时，使用反斜杠转义。

\*这不会变成斜体\*
\# 这不会变成标题

LaTeX 公式

行内公式：

这是行内公式 $E = mc^2$。

块级公式：

$$
\sum_{i=1}^{n} i = \frac{n(n+1)}{2}
$$

更多公式写法见 Latex自查表。

常见排版规范

空格

  • 中文与英文单词之间建议加空格：使用 Markdown 编写文档。
  • 中文与数字之间建议加空格：支持 3 种模式。
  • 行内代码两侧建议加空格：运行 npm test 后查看结果。

标点

  • 中文正文使用中文标点：，。；：？！。
  • 英文命令、代码、URL 内保持英文标点。
  • 列表项如果是短语，末尾可不加句号；如果是完整句子，建议加句号。

标题

  • 标题要能概括本节内容。
  • 不用“注意”“说明”“其他”作为孤立标题，改为“注意事项”“配置说明”“其他限制”。
  • 同一层级标题保持语法一致。

列表

  • 列表前后保留空行。
  • 列表项不要过长，超过两三行时考虑拆成小节。
  • 有序列表只用于真实步骤，不要为了好看强行编号。

代码与命令

  • 命令必须放进代码块或行内代码。
  • 多行代码块写明语言。
  • 示例代码要能复制运行，省略部分要明确标注。

链接

  • 链接文字要说明目标内容，不写“点击这里”。
  • 内部知识库优先用 Obsidian 双链。
  • 外部链接要确认可访问，必要时注明来源或访问日期。

文件命名

建议：

  • 笔记文件名使用清楚的中文或英文短语。
  • 项目文档和资源文件优先使用英文小写、短横线分隔。
  • 避免使用特殊符号、空格和过长文件名。

可复制模板

学习笔记模板

---
tags:
  - 学习笔记
aliases:
  - 主题别名
---
 
# 主题名称
 
## 背景
 
这项知识解决什么问题？适用于什么场景？
 
## 核心概念
 
- 概念 1：
- 概念 2：
- 概念 3：
 
## 使用方法
 
1. 第一步：
2. 第二步：
3. 第三步：
 
## 示例
 
```语言
示例代码
```
 
## 常见问题
 
| 问题 | 原因 | 解决办法 |
| --- | --- | --- |
| 现象 | 原因 | 处理方式 |
 
## 相关链接
 
- [[相关笔记]]
- [外部资料](https://example.com)

工具使用说明模板

---
tags:
  - 工具
  - 使用说明
---
 
# 工具名称使用说明
 
## 适用场景
 
说明这个工具解决什么问题，不适合什么场景。
 
## 安装与准备
 
```powershell
安装命令
```
 
## 基本用法
 
```powershell
常用命令
```
 
## 参数说明
 
| 参数 | 是否必填 | 默认值 | 说明 |
| --- | --- | --- | --- |
| 参数名 | 是 | 无 | 参数用途 |
 
## 示例
 
### 示例一：场景名称
 
```powershell
可复制命令
```
 
说明执行结果和注意事项。
 
## 常见问题
 
| 现象 | 可能原因 | 处理方式 |
| --- | --- | --- |
| 报错信息 | 原因 | 解决办法 |
 
## 检查清单
 
- [ ] 已确认运行目录。
- [ ] 已确认依赖安装完成。
- [ ] 已确认配置文件存在。
- [ ] 已记录常见错误和解决办法。

README 模板

# 项目名称
 
## 简介
 
一句话说明项目用途。
 
## 功能
 
- 功能 1
- 功能 2
- 功能 3
 
## 环境要求
 
| 依赖 | 版本 |
| --- | --- |
| Node.js | 20+ |
 
## 安装
 
```powershell
npm install
```
 
## 运行
 
```powershell
npm run dev
```
 
## 配置
 
| 配置项 | 默认值 | 说明 |
| --- | --- | --- |
| PORT | 3000 | 服务端口 |
 
## 测试
 
```powershell
npm test
```
 
## 目录结构
 
```text
project/
  src/
  tests/
  README.md
```
 
## 常见问题
 
- 问题：
- 原因：
- 解决：

会议纪要模板

# 会议纪要：会议主题
 
## 基本信息
 
| 项目 | 内容 |
| --- | --- |
| 时间 | YYYY-MM-DD HH:mm |
| 参会人 | A、B、C |
| 记录人 | A |
 
## 背景
 
说明为什么开会。
 
## 讨论要点
 
- 要点 1
- 要点 2
- 要点 3
 
## 结论
 
- 结论 1
- 结论 2
 
## 待办
 
- [ ] 事项：负责人，截止时间。
- [ ] 事项：负责人，截止时间。

关系图谱

最近的笔记

反向链接