如何解决Asciidoctor书籍中引入自定义属性后定义文本被渲染的问题

问题原因 #

直接引入普通.adoc格式的属性文件时，Asciidoctor会将属性定义语句当作正文内容渲染输出，导致章节末尾出现:appname: MyApp这类文本。

解决方法 #

• 方法1：给include指令添加:only-include属性
  修改章节文件中的include语句，添加该属性后，Asciidoctor仅处理文件内的属性定义，不会输出内容：

  include::.attributes.adoc[only-include]
  

  注意：你之前的include语句里文件名拼写错误（.attriutes.adoc多了一个i），需修正为实际文件名.attributes.adoc，否则会出现文件找不到的问题。

• 方法2：将属性文件标记为纯属性定义类型
  在.attributes.adoc文件开头添加一行:doctype: attributes，明确告诉Asciidoctor这是纯属性文件，引入时不会渲染内容：

  :doctype: attributes
  :appname: MyApp
  

  之后章节中的include语句保持原样即可，但同样要注意文件名拼写正确。

• 方法3：使用全局属性文件（推荐）
  如果是整本书共用这些属性，无需在每个章节文件中添加include语句，直接在构建命令中指定全局属性文件即可：

  asciidoctor -a attributes-file=.attributes.adoc book.adoc
  

  这样所有章节都会自动加载这些属性，彻底避免渲染问题。

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