Markdown 写作完全指南

Markdown 是一种轻量级标记语言，可以用纯文本写出结构化文档。本指南覆盖 Atom 博客支持的所有常用语法，以及 Atom 为长文额外准备的几处排版增强。

标题

使用 # 表示标题（1-6 级）：

# 一级标题
## 二级标题
### 三级标题

正文里的 ## 标题左侧会自动带一根黄铜色刻度线，作为阅读时的定位锚点。

段落与强调

普通文本，**加粗**，*斜体*，~~删除线~~，`行内代码`

效果：普通文本，加粗，斜体，删除线，行内代码

💡 正文引用块不使用斜体——中文斜体是浏览器伪斜体，很不好看。引用块改用左侧色条 + 淡色底来区分。

列表

无序列表：

- 项目 A
- 项目 B
  - 子项目
- 项目 C

有序列表：

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

链接

[链接文字](https://example.com)
[带标题的链接](https://example.com "鼠标悬停文字")

站内链接请用根路径（如 /blog/），Atom 会自动加上部署子路径前缀。

图片

![替代文本](图片URL)

Atom 的 Markdown 图片默认会加上 loading="lazy" 和 decoding="async"（由 remark 插件自动完成），但你显式写过的属性不会被覆盖。

点击正文里的图片可以打开灯箱预览。

代码块

三个反引号 + 语言标识启用语法高亮（基于 Shiki）：

```javascript
function greet(name) {
  return `Hello, ${name}!`;
}
```

function greet(name) {
  return `Hello, ${name}!`;
}

支持的语言包括 javascript、typescript、python、bash、json、html、css、yaml、markdown、rust、go 等上百种。

代码块右上角有复制按钮（悬停出现，移动端常驻），点击后按钮会短暂变成”已复制”。

表格

| 列 1 | 列 2 | 列 3 |
|------|------|------|
| A1   | A2   | A3   |
| B1   | B2   | B3   |

表格会被自动包进一个可横向滑动的容器。在 320px 窄屏上，表格自己左右滑动，页面不会跟着横向滚动——这是 Atom 的 rehype 插件做的处理，你不需要写任何额外代码。

引用

> 这是一段引用文字。
> 可以跨多行。

这是一段引用文字。 可以跨多行。

水平线

三个短横线或星号：

---

---

Atom 的排版增强

除了标准语法，Atom 还会对内容做几处自动处理：

正文首字下沉只在第一个元素是段落时生效。如果你的文章以列表或引用开头，它会自动让位给第一段正文。

Frontmatter 元数据

每篇文章顶部用 YAML 格式声明元数据：

---
title: 文章标题
description: 用于 SEO 与社交分享卡片
pubDate: 2026-09-20
updatedDate: 2026-09-21          # 可选：文章更新时间
heroImage: /medias/hero.jpg     # 可选：文章顶部大图
featuredImage: /medias/og.jpg   # 可选：OG 专用封面（优先于 heroImage）
category: 随笔                  # 单数分类
tags: [标签1, 标签2]            # 复数标签
reward: true                    # 可选：显示打赏码
draft: false                    # 草稿，构建时过滤
---

字段不满足 schema 会在构建时直接报错并指出具体位置。

实战建议

1. 保持空行 —— 段落、标题、列表之间空一行，渲染更稳定
2. 代码块标注语言 —— 方便语法高亮，对屏幕阅读器也友好
3. 图片控制大小 —— Markdown 原生不支持，HTML <img> 标签可控
4. 描述要短 —— Frontmatter 的 description 用于 SEO 摘要，建议 50-150 字
5. 合理分类 —— 分类是单数（一篇文章归一类），标签是复数（一篇文章可多个）
6. 段落别太长 —— Atom 的正文栏宽 740px、行高 1.85，超过 6 行的段落建议拆开

掌握这些语法，你就能高效地写出漂亮的博客文章了！ 🎉