今天开始着手更新文档，使整个项目看起来更加的正规。说程序员最讨厌两件事：一是别人的代码从来不写注释；二是为自己的代码写注释。这凸显了注释在团队开发的重要性。而系统使用文档则可以为客户使用系统、测试人测试系统提供指导，也可以防止一些扯皮的事件发生。
示例代码：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的代码整理规则相同。
如此以来，无论是在入口文档直接浏览，还在一级文档中浏览、或是在二级文档中直接浏览，都可以正常的获取到图片。不仅如此，该写法还支持由子目录文档向上引用父目录文档。