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[列表頁]

sub二、sub21的代碼整理規則相同。

如此以來，不管是在入口文檔直接瀏覽，還在一級文檔中瀏覽、或是在二級文檔中直接瀏覽，均可以正常的獲取到圖片。不只如此，該寫法還支持由子目錄文檔向上引用父目錄文檔。