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