求助：AsciiDoc v9.0.5（Mac OS 11.2）中图片无法渲染的问题

从你的描述来看，最可能的原因是图片宏的语法不完整，另外我们也可以一步步排查其他可能性：

1. 修正图片宏的语法 #

不管你使用的是传统Python版AsciiDoc还是Ruby版Asciidoctor，图片宏都需要以[]结尾——哪怕你不需要设置任何额外属性（比如宽度、替代文本）。你当前写的是：

image:sunset.jpg

这会被AsciiDoc当成普通文本直接输出，正确的写法应该是：

// 行内图片（和文本在同一行）
image:sunset.jpg[]

// 块级图片（单独占一行，适合展示较大的图片）
image::sunset.jpg[]

修改后重新执行asciidoc {filename}，应该就能正确渲染图片了。

2. 确认你使用的AsciiDoc工具版本 #

Homebrew上的asciidoc包可能指向不同的工具，两者的语法细节略有差异：

• 传统Python版AsciiDoc：版本通常是8.x（比如8.6.10），对语法要求更严格；
• Ruby版Asciidoctor：版本是1.x或2.x，语法更灵活，但同样需要[]来识别宏。

你可以运行以下命令确认版本：

asciidoc --version

如果输出是Asciidoctor x.x.x，说明你用的是Asciidoctor；如果是asciidoc x.x.x (Python-based)，那就是传统AsciiDoc。块级图片在传统版本里必须用image::前缀。

3. 检查命令行参数是否误禁用了宏 #

如果语法没问题，再确认你有没有在执行命令时添加了禁用宏的参数，比如传统AsciiDoc的--no-macros。如果有这个参数，宏会被直接忽略，去掉它即可。

4. 验证图片路径的正确性（语法修复后） #

虽然你说试过多种路径写法，但还是可以再确认几点：

• 如果你设置了:imagesdir:属性，要确保图片路径是相对于这个目录的；
• 绝对路径在传统AsciiDoc里写成image:/full/path/to/sunset.jpg[]，在Asciidoctor里写成image:///full/path/to/sunset.jpg[]；
• 相对路径加./前缀是更稳妥的写法：image:./sunset.jpg[]。

如果以上步骤都试过还是不行，可以尝试生成调试日志，查看宏是否被正确识别：

asciidoc -v {filename}

详细的日志会显示AsciiDoc处理文档的全过程，能帮你定位问题所在。

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