4

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

示例代码: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[列表页]

image.png

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

reamdme.adoc

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

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

= 子文件夹2
include::sub2/readme.adoc[]
  • ➊ 在此处引用了sub1

image.png

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

分析原因:

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

生产环境

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

image.png
再比如还可以由根文档先引入二级文档,再由二级文档引用一级文档。

解决方法

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

: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的代码整理规则相同。

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


潘杰
3.1k 声望238 粉丝