文档标题（H1）

主要章节（H2）

小节（H3）

子小节（H4）

另一个主要章节（H2）

小节（H3）

不要这样：

标题 1

标题 3（跳过了 H2）

文档标题

这是文档的简介。

第一章

这是第一章的内容。

1.1 小节

这是小节的内容。

• 列表项目 1
• 列表项目 2

代码示例：

console.log("Hello World");

第二章

这是第二章的内容。

在这篇文章中，我们将讨论 Markdown 的使用，
以及如何在 GitHub 上应用它。

我们还会提到 Stack Overflow 的最佳实践。

这样做的好处：

1. 链接集中管理
2. 正文更易阅读
3. 便于修改和维护

项目文档

• 快速开始
• API 文档
• 常见问题

图片引用：

相对路径的优势：

• 便于文档迁移
• 支持离线浏览
• 减少维护成本

好的做法：

function calculateSum(a, b) {
  return a + b;
}

def calculate_sum(a, b):
  return a + b

避免这样：

function calculateSum(a, b) {
  return a + b;
}

// 用户认证中间件
function authenticateUser(req, res, next) {
  // 从请求头获取 token
  const token = req.headers.authorization;
  
  if (!token) {
      // 如果没有 token，返回 401 错误
      return res.status(401).json({ error: 'No token provided' });
  }
  
  try {
      // 验证 token 的有效性
      const decoded = jwt.verify(token, process.env.JWT_SECRET);
      req.user = decoded;
      next();
  } catch (error) {
      // token 无效时的处理
      return res.status(403).json({ error: 'Invalid token' });
  }
}

推荐格式：

也可以接受（功能相同）：

好的做法：
这是一个适当长度的段落。它不会太长以至于难以阅读，
也不会太短以至于显得支离破碎。

避免：
这是一个非常非常非常非常非常非常非常非常非常非常非常非常非常非常非常非常非常非常长的段落，它会让读者感到疲劳，难以跟踪阅读的位置。

也避免：
太短。
的段落。
很难读。

项目特性

我们的项目具有以下特性：

• 高性能：优化的算法和数据结构
• 易用性：直观的 API 设计
• 可扩展：插件化架构
• 跨平台：支持多种操作系统

安装要求

在开始之前，请确保你的系统满足以下要求：

1. Node.js 版本 >= 14.0.0
2. npm 版本 >= 6.0.0
3. 操作系统：Windows 10+、macOS 10.15+、Ubuntu 18.04+
4. 内存：至少 4GB RAM

好的做法：
这是第一句话。
这是第二句话。
这是第三句话。

避免：
这是第一句话。这是第二句话。这是第三句话。

优势：

• Git diff 更清晰
• 更容易追踪修改
• 减少合并冲突

docs/
├── en/
│ ├── README.md
│ ├── getting-started.md
│ └── api.md
├── zh/
│ ├── README.md
│ ├── getting-started.md
│ └── api.md
└── README.md # 主文档，链接到各语言版本

在每个文档中添加语言切换：

• English
• 中文

图片使用建议

本地图片

在线图片（确保稳定性）

压缩大图片

对于大图片，考虑：

• 使用适当的分辨率
• 选择合适的格式（WebP、PNG、JPEG）
• 提供多种尺寸版本

添加 alt 文本

所有图片都应该有描述性的 alt 文本，
这对无障碍访问和 SEO 都很重要。

文档标题 - 适合文本转换的清晰标题

具有文本友好标题的章节

小节：易于在文本格式中阅读

使用在转换过程中保持清洁的一致格式：

• 项目符号在md转文本输出中保持结构
• 保持段落长度适中以提高可读性
• 使用清晰、描述性的标题便于文本导航

粗体强调在文本转换中效果很好。
斜体文本在markdown转文本处理中保持。

代码块即使在文本格式中也提供上下文
完美适用于markdown转文本文档工作流程

引用块在文本转换中保持意义
对突出重要信息很有用

像Markdown转文本工具这样的链接
在文本输出中保持可访问性。

Markdown转文本工作流程推荐工具

文本转换编辑器

• Typora：具有出色文本导出功能的所见即所得编辑器
• Mark Text：具有清洁文本输出的实时预览
• VS Code：针对文本转换优化的Markdown扩展
• Obsidian：具有卓越md转文本功能的笔记

Markdown转换器工具

• Pandoc：具有文本输出的通用文档转换器
• Marked：快速的markdown转文本处理
• Turndown：用于文本工作流程的HTML到markdown转换
• Remark：用于文本转换的强大markdown处理器

文本处理平台

• GitBook：具有清洁文本导出的文档
• VuePress：支持文本转换的静态站点生成器
• Gatsby：具有markdown转文本功能的React平台
• Docusaurus：为文本输出优化的Facebook平台

在线文本转换工具

• Markdown转文本转换器：专业的markdown转文本处理
• StackEdit：具有文本导出功能的在线编辑器
• Dillinger：具有清洁文本输出的云markdown编辑器
• Markdown实时预览：实时文本转换预览

命令行文本处理

• Pandoc CLI：命令行markdown转文本转换
• Marked CLI：从markdown进行快速文本处理
• Remark CLI：高级文本转换工作流程
• 自定义脚本：自动化md转文本批处理