MKDocs 1.4.3渲染单引号为’的问题排查与修复求助

原因 #

这是字符编码解析不匹配导致的乱码：MKDocs默认启用了smartquotes扩展，会把Markdown里的直引号（'、"）自动转换为UTF-8编码的智能弯引号（’、“）。但如果页面的编码声明异常，或者本地服务的输出编码未正确设置，UTF-8格式的弯引号会被错误解析为ISO-8859-1编码，从而显示出’、“这类乱码字符。

修复方法 #

方法1：关闭智能引号转换 #

如果不需要弯引号，直接禁用smartquotes扩展即可解决问题。在项目根目录的mkdocs.yml中添加或修改配置：

markdown_extensions:
  - smartquotes:
      disable: true

修改后重启mkdocs serve，直引号会保持原样渲染，不会出现乱码。

方法2：确保编码配置正确 #

如果需要保留智能弯引号，需确保全站编码统一为UTF-8：

1. 在mkdocs.yml中显式设置编码：

encoding: utf-8

2. 确认本地的Markdown文件均以UTF-8编码保存（大多数编辑器默认支持，可在保存时选择编码）。
3. MKDocs Material主题默认会在页面头部生成<meta charset="UTF-8">标签，无需额外修改，若自定义了模板需检查该标签是否存在。

内容的提问来源于stack exchange，提问作者hpy