Markdown

介绍 Markdown

#resource / markdown #type / concept #status / growing

[!info] related notes

做市商

markdown编辑器实现这份笔记内容填充旨在保持简洁性与实用性，特别针对 Obsidian 用户的视角进行了优化。

[!info] 上级索引

Markdown

1. 概览（Overview）

这是一个什么东西？ 一种轻量级标记语言，允许人们使用易读易写的纯文本格式编写文档，然后将其转换成有效的 HTML 文档。
它解决什么问题？适用场景是什么？ 解决写作时的排版干扰问题。适用于撰写技术文档、博客文章、个人笔记（如 Obsidian）、README 文件等。
一句话总结 “所写即所得”之前的“所见即所想”——专注于内容的极简排版工具。

2. 关键概念（Core Concepts）

纯文本（Plain Text）： 内容和格式指令都包含在文本字符中，不依赖特定软件打开。
渲染（Rendering）： 将 Markdown 语法（如 **加粗**）转换为视觉样式（如加粗）的过程。
方言（Flavors）： 标准 Markdown 的不同变体，最常用的是 GFM (GitHub Flavored Markdown)，Obsidian 也基本遵循此标准。

3. 安装与环境准备（Installation / Setup）

系统要求 无。任何操作系统、任何文本编辑器（记事本、TextEdit）均可编辑。
推荐工具
- Obsidian / Logseq: 双链笔记工具。
- Typora: 优秀的所见即所得编辑器。
- VS Code: 程序员首选，配合 Markdown All in One 插件。
文件扩展名 通常为 .md 或 .markdown。

4. 快速开始（Quick Start）

标题与文本

# 一级标题
## 二级标题
**加粗文本** 与 *斜体文本*

列表

- 无序列表项 1
- 无序列表项 2
1. 有序列表项 1

链接与图片

[显示文本](链接地址)
![图片描述](图片链接/本地路径)

引用
```
> 这是一段引用文本
```

5. 进阶使用（Advanced Usage）

代码块（Code Blocks） 使用三个反引号 ``` 包裹代码，并指定语言（如 python, js）：
```
```python
print("Hello World")
```

表格（Tables）

| 标题1 | 标题2 |
| ----- | ----- |
| 内容A | 内容B |

任务列表（Task List）

- [ ] 待办事项
- [x] 已完成事项

数学公式（LaTeX） 使用 $$ 包裹：

$$ E=mc^2 $$

6. 目录结构（Project Structure）

虽然 Markdown 是单文件格式，但在项目（如 GitHub 仓库或 Hexo 博客）中通常遵循以下结构：

project/
  ├── README.md        # 项目入口说明
  ├── docs/            # 文档文件夹
  │   ├── manual.md    # 手册
  │   └── assets/      # 存放图片/附件
  │       └── logo.png
  └── LICENSE.md       # 许可协议

7. 常见问题（FAQ）

Q1: 为什么我的换行在预览时不显示？
- Markdown 标准中，单次换行会被视为空格。若需强制换行，请在行尾加两个空格或使用 <br>，或者在段落间空一行。
Q2: 图片太大怎么调整？
- 标准 Markdown 不支持调整大小。在 Obsidian 中可使用 ![alt|300](/vault-assets/image.png) 调整宽度为 300px。

8. 排错指南（Debug / Troubleshooting）

常见报错/渲染失败：
1. 标题不生效： # 后面必须加一个空格（# 标题 ✅，#标题 ❌）。
2. 列表错乱： 列表项之间包含子内容时，缩进必须对齐（通常是 2 或 4 个空格）。
3. 引用断裂： 区块引用若要换行，每行前都需要加 >。

9. 最佳实践（Best Practices）

语义化标题： 不要跳级使用标题（如直接从 H1 跳到 H3），这影响文档结构和大纲生成。
保持源码整洁： 在标题、列表、代码块前后保留空行，这能最大程度兼容不同的渲染引擎。
相对路径： 引用图片时尽量使用相对路径（如 ./assets/img.png），便于迁移。

10. 资源与参考（Resources）

官方/权威指南： Markdown Guide
GitHub 规范： GFM Spec
在线练习： Markdown Tutorial

11. 个人笔记（Personal Notes）

Obsidian 特有技巧：
- 使用 [[内部链接]] 进行双向链接。
- 使用 ![[内部链接]] 嵌入笔记内容。
- Callout 语法：> [!info] 说明（如本文开头的样式）。
心得： 它是目前通用性最强的笔记格式，学会它等于掌握了所有开发者工具的通用语言。不要在 Markdown 里过度纠结复杂的 CSS 排版，保持内容优先。

Markdown 语法速查

语法	说明	实例
标题	使用 # 创建不同级别的标题，# 为一级标题，## 为二级标题，以此类推	`# 一级标题` `## 二级标题` `### 三级标题`
段落和换行	段落间用空行分隔，行末加两个空格或使用强制换行	`第一段文字` `第二段文字` `行末两个空格` `换行`
粗体	使用 ** 或 __ 包围文本	`粗体文本` 或 `__粗体文本__`
斜体	使用 * 或 _ 包围文本	`斜体文本` 或 `_斜体文本_`
粗体和斜体	使用 *** 或 ___ 包围文本	`*粗体斜体*` 或 `___粗体斜体___`
删除线	使用 ~~ 包围文本	`~~删除的文本~~`
无序列表	使用 -、* 或 + 开头	`- 项目1` `- 项目2` `- 子项目`
有序列表	使用数字加 . 开头	`1. 第一项` `2. 第二项` `1. 子项`
任务列表	使用 - [ ] 或 - [x] 创建复选框	`- [ ] 未完成任务` `- [x] 已完成任务`
链接	使用文本创建链接	`[GitHub](https://github.com)`
图片	使用 !替代文本插入图片	`![GitHub Logo](https://github.githubassets.com/images/modules/site/github-logo.png)`
内联代码	使用 ` 包围代码	`console.log('Hello')`
代码块	使用 ``` 包围多行代码，可指定语言	````javascript`<br>`console.log(‘Hello’);` ```
引用块	使用 > 开头创建引用	`> 这是一个引用` `>> 嵌套引用`
表格	使用	分隔列，- 分隔表头	`	列1	列2
水平线	使用 --- 或 *** 或 ___	`---`
自动链接	URL 会自动转换为链接	`https://github.com`
表情符号	使用 :emoji: 语法	`:smile:` 显示为 😄
脚注	使用 [^1] 定义脚注	`这是脚注[^1]` `[^1]: 脚注内容`
折叠内容	使用 `<details>` 和 `<summary>`	`<details><summary>点击展开</summary>隐藏内容</details>`
提及	使用 @username 提及用户	`@octocat`
引用问题/PR	使用 `#number` 引用	`#123`	包围多行代码，可指定语言	````javascript`<br>`console.log(‘Hello’);` ```
引用块	使用 > 开头创建引用	`> 这是一个引用` `>> 嵌套引用`
表格	使用	分隔列，- 分隔表头	`	列1	列2
水平线	使用 --- 或 *** 或 ___	`---`
自动链接	URL 会自动转换为链接	`https://github.com`
表情符号	使用 :emoji: 语法	`:smile:` 显示为 😄
脚注	使用 [^1] 定义脚注	`这是脚注[^1]` `[^1]: 脚注内容`
折叠内容	使用 `<details>` 和 `<summary>`	`<details><summary>点击展开</summary>隐藏内容</details>`
提及	使用 @username 提及用户	`@octocat`
引用问题/PR	使用 `#number` 引用	`#123`
数学公式	使用 $ 包围 LaTeX 公式	$E = mc^2$ 或 `

$$ \sum_{i=1}^n x_i $$` | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | |