Markdown 写作指南

Appearance

常见问题与解决方案 ​

在使用 Markdown 和 VSCode 进行写作时，您可能会遇到一些常见问题。本指南将为您提供这些问题的解决方案。

格式相关问题 ​

1. 表格格式混乱 ​

问题：创建的表格在预览中显示不整齐。

解决方案：使用 Prettier 格式化工具自动对齐表格。

markdown
<!-- 格式化前 -->
| 姓名 | 年龄 | 城市 |
| ---- | ---- | ---- |
| 张三 | 25 | 北京 |
| 李四 | 30 | 上海 |

<!-- 格式化后 -->
| 姓名 | 年龄 | 城市 |
| ---- | ---- | ---- |
| 张三 | 25   | 北京 |
| 李四 | 30   | 上海 |

操作步骤：

  1. 在 Markdown 文件中右键点击
  2. 选择 "Format Document" 或按 Shift+Alt+F

2. 列表缩进不正确 ​

问题：嵌套列表的缩进显示不正确。

解决方案：确保使用正确的缩进（通常是2个或4个空格）。

markdown
<!-- 正确的嵌套列表 -->
1. 第一项
   - 子项1
   - 子项2
2. 第二项
   1. 子项1
   2. 子项2

<!-- 错误的嵌套列表 -->
1. 第一项
    - 子项1
    - 子项2
2. 第二项
    1. 子项1
    2. 子项2

图片相关问题 ​

1. 图片无法显示 ​

问题：在预览中图片无法正常显示。

解决方案：

  1. 检查图片路径是否正确
  2. 确保图片文件存在
  3. 检查文件名大小写是否匹配
markdown
<!-- 相对路径示例 -->
![示意图](./images/diagram.png)

<!-- 绝对路径示例 -->
![示意图](/images/diagram.png)

<!-- 网络图片 -->
![示意图](https://example.com/image.png)

2. 图片大小不合适 ​

问题：图片在文档中显示过大或过小。

解决方案：使用 HTML 标签调整图片大小。

markdown
<!-- 调整图片宽度为50% -->
<img src="./images/diagram.png" width="50%" />

<!-- 设置固定宽度和高度 -->
<img src="./images/diagram.png" width="300" height="200" />

<!-- 居中显示图片 -->
<div align="center">
  <img src="./images/diagram.png" width="70%" />
</div>

预览相关问题 ​

1. 实时预览不同步 ​

问题：编辑器中的光标位置与预览窗口不同步。

解决方案：

  1. 确保安装了 "Markdown Preview Enhanced" 扩展
  2. 在扩展设置中启用同步滚动功能
json
{
  "markdown-preview-enhanced.syncPreviewOnUpdate": true,
  "markdown-preview-enhanced.scrollSync": true
}

2. 数学公式无法渲染 ​

问题：LaTeX 数学公式在预览中无法正确显示。

解决方案：

  1. 确保安装了支持 LaTeX 的扩展（如 "Markdown Preview Enhanced"）
  2. 使用正确的语法格式
markdown
<!-- 行内公式 -->
这是行内公式 $E = mc^2$ 的示例。

<!-- 块级公式 -->
$$
\begin{aligned}
\nabla \cdot \vec{E} &= \frac{\rho}{\varepsilon_0} \\
\nabla \cdot \vec{B} &= 0
\end{aligned}
$$

扩展相关问题 ​

1. 扩展无法正常工作 ​

问题：安装的扩展没有按预期工作。

解决方案：

  1. 检查扩展是否已正确安装
  2. 重启 VSCode
  3. 检查扩展的设置选项
bash
# 重启 VSCode
# 方法1：在命令面板中输入 "Reload Window"
# 方法2：关闭并重新打开 VSCode

2. 扩展冲突 ​

问题：多个扩展之间产生冲突，导致功能异常。

解决方案：

  1. 禁用不必要的扩展
  2. 逐个启用扩展以确定冲突源
  3. 查找功能相似的扩展并选择最适合的
bash
# 在终端中列出已安装的扩展
code --list-extensions

# 禁用特定扩展
code --disable-extension extension-id

导出相关问题 ​

1. PDF 导出格式错乱 ​

问题：导出的 PDF 文件格式与预览不一致。

解决方案：

  1. 使用 "Markdown PDF" 扩展进行导出
  2. 调整扩展的设置选项
json
{
  "markdown-pdf.styles": ["./style.css"],
  "markdown-pdf.includeDefaultStyles": true,
  "markdown-pdf.executablePath": ""
}

2. 导出文件中文显示异常 ​

问题：导出的 PDF 文件中中文显示为方框或乱码。

解决方案：

  1. 在设置中指定中文字体
  2. 确保系统中安装了所需字体
json
{
  "markdown-pdf.executablePath": "",
  "markdown-pdf.styles": ["./style.css"],
  "markdown-pdf.displayHeaderFooter": true
}
css
/* style.css */
body {
  font-family: "Microsoft YaHei", "SimHei", sans-serif;
}

性能优化建议 ​

1. 大文件编辑卡顿 ​

问题：编辑大型 Markdown 文件时出现卡顿。

解决方案：

  1. 启用大文件优化设置
  2. 分割大型文件为多个小文件
json
{
  "files.largeFileSize": 10240,
  "editor.largeFileOptimizations": true
}

2. 预览加载缓慢 ​

问题：包含大量图片或复杂格式的文档预览加载缓慢。

解决方案：

  1. 优化图片大小和格式
  2. 减少复杂 HTML 标签的使用
  3. 使用分页或折叠功能

通过掌握这些常见问题的解决方案，您可以更顺利地使用 Markdown 和 VSCode 进行写作。