Markdown 写作指南

Appearance

Markdown 与 VSCode 最佳实践 ​

通过遵循这些最佳实践，您可以更高效地使用 Markdown 和 VSCode 进行写作。

文档结构最佳实践 ​

1. 使用清晰的文件命名 ​

  • 使用小写字母和连字符分隔单词
  • 避免使用特殊字符和空格
  • 文件名应能清楚表达文件内容
bash
# 推荐的命名方式
project-overview.md
installation-guide.md
api-reference.md

# 不推荐的命名方式
Project Overview.md
安装指南.md
API 文档.md

2. 建立统一的目录结构 ​

bash
project/
├── README.md
├── docs/
│   ├── getting-started.md
│   ├── user-guide.md
│   ├── api/
│   │   ├── overview.md
│   │   └── endpoints.md
│   └── guides/
│       ├── installation.md
│       └── troubleshooting.md
└── assets/
    ├── images/
    └── diagrams/

3. 编写有效的 README 文件 ​

README 文件应该包含以下内容：

markdown
# 项目名称

简短描述项目的功能和用途。

## 目录

- [快速开始](#快速开始)
- [安装](#安装)
- [使用方法](#使用方法)
- [贡献](#贡献)
- [许可证](#许可证)

## 快速开始

提供让读者快速上手的简要说明。

## 安装

详细说明安装步骤。

## 使用方法

展示如何使用项目的主要功能。

## 贡献

说明如何为项目做贡献。

## 许可证

说明项目的许可证信息。

写作最佳实践 ​

1. 使用语义化标题 ​

  • 使用标题层次结构清晰表达内容关系
  • 不要跳过标题级别（如从 H1 直接跳到 H3）
markdown
# 文档标题 (H1)

## 章节标题 (H2)

### 小节标题 (H3)

#### 子小节标题 (H4)

2. 合理使用列表 ​

  • 无序列表用于并列项
  • 有序列表用于步骤或有顺序的项
markdown
## 无序列表示例
- 第一项
- 第二项
- 第三项

## 有序列表示例
1. 第一步
2. 第二步
3. 第三步

## 嵌套列表示例
1. 主要步骤
   - 子步骤1
   - 子步骤2
2. 另一个主要步骤
   1. 子步骤1
   2. 子步骤2

3. 有效使用链接 ​

  • 使用描述性文字作为链接文本
  • 避免使用"点击这里"等无意义的链接文本
markdown
<!-- 推荐 -->
有关详细信息，请参阅[安装指南](./installation.md)。

<!-- 不推荐 -->
有关详细信息，请[点击这里](./installation.md)。

VSCode 配置最佳实践 ​

1. 个性化设置 ​

创建适合 Markdown 写作的设置：

json
{
  "editor.fontSize": 16,
  "editor.lineHeight": 1.6,
  "editor.wordWrap": "on",
  "editor.rulers": [80],
  "files.trimTrailingWhitespace": true,
  "files.insertFinalNewline": true,
  "markdown.preview.fontSize": 16,
  "markdown.preview.scrollEditorWithPreview": true,
  "markdown.preview.scrollPreviewWithEditor": true
}

2. 快捷键优化 ​

配置常用的快捷键：

json
[
  {
    "key": "ctrl+shift+b",
    "command": "markdown.preview.toggle",
    "when": "editorTextFocus && editorLangId == 'markdown'"
  },
  {
    "key": "ctrl+shift+f",
    "command": "editor.action.formatDocument",
    "when": "editorTextFocus && editorLangId == 'markdown'"
  }
]

3. 工作区配置 ​

为项目创建专门的工作区配置文件：

json
{
  "folders": [
    {
      "path": "."
    }
  ],
  "settings": {
    "markdown-preview-enhanced.previewTheme": "github-light.css",
    "markdown-preview-enhanced.codeBlockTheme": "default.css",
    "markdown-preview-enhanced.mathRenderingOption": "KaTeX"
  },
  "extensions": {
    "recommendations": [
      "yzhang.markdown-all-in-one",
      "shd101wyy.markdown-preview-enhanced",
      "streetsidesoftware.code-spell-checker"
    ]
  }
}

团队协作最佳实践 ​

1. 版本控制规范 ​

  • 每个功能或修复应有独立的分支
  • 提交信息应清晰描述更改内容
  • 定期同步主分支的更改
bash
# 创建功能分支
git checkout -b feature/add-user-guide

# 提交更改
git add docs/user-guide.md
git commit -m "docs: 添加用户指南初稿"

# 合并前同步主分支
git checkout main
git pull origin main
git checkout feature/add-user-guide
git rebase main

2. 文档审阅流程 ​

建立清晰的文档审阅流程：

  1. 作者完成初稿
  2. 提交 Pull Request
  3. 指定审阅者
  4. 审阅者提供反馈
  5. 作者根据反馈修改
  6. 审阅通过后合并

3. 模板和样式统一 ​

创建文档模板确保一致性：

markdown
<!-- 文档模板 -->
# {{文档标题}}

## 概述

简要描述文档内容和目的。

## 目标读者

说明文档的目标读者群体。

## 先决条件

列出阅读本文档前需要了解的知识。

## 目录

- [概述](#概述)
- [主要章节](#主要章节)
- [总结](#总结)

## 主要章节

详细内容。

## 总结

总结文档要点。

## 参考资料

- [链接1](url1)
- [链接2](url2)

工具使用最佳实践 ​

1. 扩展管理 ​

  • 只安装必要的扩展
  • 定期更新扩展
  • 为不同项目配置不同的扩展集

2. 自动化工具 ​

  • 使用 Prettier 统一代码格式
  • 使用拼写检查工具避免拼写错误
  • 配置任务自动化常见操作
json
{
  "scripts": {
    "format": "prettier --write \"docs/**/*.md\"",
    "lint": "markdownlint \"docs/**/*.md\"",
    "check-links": "link-checker docs/**/*.md"
  }
}

3. 备份和同步 ​

  • 使用 Git 进行版本控制
  • 定期推送到远程仓库
  • 考虑使用云存储服务进行额外备份

通过遵循这些最佳实践，您可以显著提高使用 Markdown 和 VSCode 进行写作的效率和质量。