asciidoc文档包含子文件时图片无法显示的一种解决方案

今天开始着手更新文档，使整个项目看起来更加的正规。说程序员最讨厌两件事：一是别人的代码从来不写注释；二是为自己的代码写注释。这凸显了注释在团队开发的重要性。而系统使用文档则可以为客户使用系统、测试人测试系统提供指导，也可以防止一些扯皮的事件发生。

示例代码：https://github.com/mengyunzhi/asciidoctor-sub-file-image-show

背景

写文档有两个常用的语言：markdown以及AsciiDoc，看到一些大牛们的readme都是拿AsciiDoc写的，索性也将团队中的项目拿AsciiDoc来写。我们说绝大多数的功能都是非常好的，比如可以在一个文件中include别一个文件。但include的过程中发生了图片无法正常显示的错误。

DEMO

这主要是由于图片文件夹的绝对位置发生了变化，举例说明：

.
├── readme.adoc
├── sub1
│   ├── assets1
│   │   └── e75b18b9.png
│   ├── readme.adoc
│   └── sub11
│       ├── assets11
│       │   └── e75b18b9.png
│       └── readme.adoc
└── sub2
    ├── assets2
    │   └── e75b18b9.png
    ├── readme.adoc
    └── sub21
        ├── assets21
        │   └── e75b18b9.png
        └── readme.adoc

比如新建如上文档目录，首页为readme.adoc。

sub1/readme.adoc

:imagesdir: assets1/    ★

图片测试

image::e75b18b9.png[列表页]

如上，直接浏览readme.adoc中效果，图片能够正常显示。

reamdme.adoc

= 子文件夹1
include::sub1/readme.adoc[] ➊

== 子文件夹11
include::sub1/sub11/readme.adoc[]

= 子文件夹2
include::sub2/readme.adoc[]

• ➊ 在此处引用了sub1

如上：在父文件中查看，图片却无法正常显示。

分析原因:

• 直接浏览时sub1/readme.adoc时，图片文件夹★值为assets1。相对于正在浏览的sub1/readme.adoc的所在目录sub，存在文件夹assets1，图片正确显示。
• 当浏览根目录下的readme.adoc时，readme.adoc引入了sub1/readme.adoc，当前图片文件夹★值为assets1。正在浏览的readme.adoc的根目录仅有sub1，sub2两个子文件夹，并不存在asserts1文件夹，图片不能正确显示。

生产环境

在实际的生产环境中，文件间的引用比上面的例子还要复杂。比如上图示在根文档中同时引入一级文档及二级文档，在根文档中引用一级文档再由一级文档中引用二级文档。

再比如还可以由根文档先引入二级文档，再由二级文档引用一级文档。

解决方法

整个问题比较绕，解决的思路也比较烧脑，在此直接给出解决方案：首先定位一下文档的根目录，并在根目录文件头中加入以下代码：

:rootpath: ./

然后在各级目录的文件中加入以下代码，比如于sub1/readme.adoc中代码整理如下：

:path: sub1/ ➊
:imagesdir: assets1/ ➋

ifdef::rootpath[]
:imagesdir: {rootpath}{path}{imagesdir}
endif::rootpath[]

ifndef::rootpath[]
:rootpath: ./../ ➌
endif::rootpath[]

图片测试

image::e75b18b9.png[列表页]

要点如下：

• ➊ 相对于根目录的路径
• ➋ 图片文件夹所在路径
• ➌ 根目录径相对于当前文件的路径

按上述规则对sub1/sub11/readme.adoc整理如下：

:path: sub1/sub11/
:imagesdir: assets11/

ifdef::rootpath[]
:imagesdir: {rootpath}{path}{imagesdir}
endif::rootpath[]

ifndef::rootpath[]
:rootpath: ./../../
endif::rootpath[]

图片测试

image::e75b18b9.png[列表页]

sub2、sub21的代码整理规则相同。

如此以来，无论是在入口文档直接浏览，还在一级文档中浏览、或是在二级文档中直接浏览，都可以正常的获取到图片。不仅如此，该写法还支持由子目录文档向上引用父目录文档。