Mengatasi Konflik Path Gambar pada AsciiDoc

Dalam proses penulisan dokumentasi teknis menggunakan AsciiDoc, saya sempat menemui satu masalah klasik namun cukup mengganggu, yaitu konflik gambar (image conflict). Masalah ini terlihat sepele, tetapi jika tidak dipahami dengan baik, dapat menyebabkan gambar tidak muncul, caption tidak terbaca, atau bahkan nama file gambar tidak dikenali sama sekali.

Saya memiliki sebuah gambar ini yang ingin dimasukkan kedalam dokumentasi asciidoctor yang nanti akan diubah menjadi pdf menggunakan asciidoctor-pdf.

Namun, saat dirender ke PDF, yang tampil hanya seperti ini

Dan struktur folder yang saya gunakan seperti ini

File utama adalah buku-cloud-stack.adoc dan saya menginisiasi direktori gambar pada file utama

:imagesdir: image

Dan saya menginisiasi gambar di folder BAB-1 pada file 1.1-konsep-dan-terminologi.adoc seperti ini

:imagesdir: ../image

Hal ini yang menimbulkan konflik saat merender .adoc ke .pdf, karena saya menginclude file 1.1-konsep-dan-terminologi.adoc ke dalam file buku-cloud-stack.adoc, maka asciidoctor bingung harus merender dari direktori yang mana.

Solusinya adalah menggunakan kondisional (if–not–defined) di asciidoc, pada file utama tetap menggunakan

:imagesdir: image

Namun pada file selain file utama agar preview gambar masih dapat terpanggil gunakan

ifndef::imagesdir[:imagesdir: ../image]

Sesuaikan bagian ../image dengan jalur direktori dan tingkat kedalaman folder yang digunakan. Apabila file berada di dalam subfolder bertingkat, maka perlu menyesuaikan path dengan keluar satu atau lebih tingkat direktori, misalnya menggunakan ../../image.