如何编写可同时适配GitHub展示与转换为正式man page的Markdown手册

解决方案 #

你遇到的问题本质是pandoc扩展Markdown语法和GitHub Flavored Markdown（GFM）对定义列表的语法支持存在差异：你当前使用的「术语和定义之间加空行」的写法是pandoc支持的扩展语法，但GFM无法识别，因此会直接把开头的:作为普通文本展示。

可以选择以下任意一种兼容写法，同时满足GitHub正常渲染、pandoc转man page格式正确的需求：

方案1：调整定义列表换行规则（最推荐） #

GFM支持的定义列表要求术语和对应的定义描述之间不能有空行，调整后的写法如下：

# OPTIONS

**-h**
: Display help

**-v**
: Verbose

**-o**, **--other**
: Some other option with a much longer description
spanning several lines

这种写法在GitHub上会自动渲染为带缩进的定义列表，不会显示多余的冒号，pandoc也能正常识别转换，生成的man page和之前的效果完全一致，不需要修改转换命令。

方案2：用嵌套缩进的无序列表（全平台兼容） #

如果需要适配更多不支持定义列表的Markdown渲染器，可以用无序列表+缩进的写法：

# OPTIONS

- **-h**  
  Display help
- **-v**  
  Verbose
- **-o**, **--other**  
  Some other option with a much longer description
  spanning several lines

这种写法所有Markdown渲染器都能正常展示缩进格式，pandoc转换为man page时也会自动识别开头粗体的内容为选项，生成的格式符合man page规范。

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