Konverter online gratis ASCIIDOC ke MD

GitHub, GitLab, dan banyak alat dokumentasi menerima Markdown tetapi tidak AsciiDoc, sehingga file .adoc mungkin perlu dikonversi sebelum dipublikasikan atau diedit di sana. Mengonversinya ke .md mempertahankan source yang mudah dibaca sekaligus menyesuaikan heading, daftar, tautan, dan blok kode ke sintaks Markdown.

Apa itu format ASCIIDOC

AsciiDoc adalah format markup plain-text yang digunakan untuk dokumentasi software, manual, buku, catatan rilis, dan file README. Ekstensi yang umum digunakan meliputi .adoc, .asciidoc, dan .ad.

File AsciiDoc biasanya dibuat atau diproses dengan Asciidoctor, implementasi Ruby modern, atau AsciiDoc processor yang lebih lama. Editor seperti Visual Studio Code, IntelliJ IDEA, dan alat dokumentasi khusus juga dapat membuat file ini karena source-nya berupa teks biasa.

AsciiDoc mendukung atribut, include directives, blok admonition, tabel, cross-reference, diagram, citation, dan struktur dokumen yang dapat digunakan kembali. Beberapa fitur ini tidak memiliki padanan langsung dalam Markdown.

Apa itu format MD

MD adalah ekstensi yang umum digunakan untuk file Markdown. Markdown adalah plain text ringan yang dirancang agar source mudah dibaca dan mudah dirender sebagai HTML. GitHub, GitLab, Bitbucket, static-site generator, wiki, aplikasi pencatat, dan code editor biasanya mendukungnya.

Markdown merupakan target praktis ketika sebuah repository memerlukan README.md, ketika kolaborator mengedit dokumentasi menggunakan alat yang berorientasi pada Markdown, atau ketika file source harus ditampilkan secara konsisten di berbagai platform code hosting. GitHub Flavored Markdown (GFM) menambahkan tabel, task list, autolink, dan fenced code block.

Cara benar-benar mengonversi ASCIIDOC ke MD

Untuk konversi lokal, instal Pandoc, lalu jalankan:

pandoc input.adoc -f asciidoc -t gfm -o output.md

Ganti input.adoc dengan nama file source dan output.md dengan lokasi tujuan yang diinginkan. Opsi -f asciidoc memilih AsciiDoc reader, -t gfm menghasilkan GitHub Flavored Markdown, dan -o menulis hasilnya ke sebuah file.

Untuk mengonversi file dengan ekstensi .asciidoc, gunakan nama sebenarnya:

pandoc manual.asciidoc -f asciidoc -t gfm -o manual.md

Jika versi Pandoc yang terinstal tidak menyediakan AsciiDoc reader, gunakan Asciidoctor untuk membuat DocBook XML terlebih dahulu, lalu konversikan file perantara tersebut:

asciidoctor -b docbook5 -o intermediate.xml input.adoc
pandoc intermediate.xml -f docbook -t gfm -o output.md

Untuk opsi tanpa instalasi, unggah file source ke 101convert.com, pilih Markdown sebagai format output, mulai konversi, lalu unduh file .md yang dihasilkan. Hindari mengunggah dokumen yang berisi informasi rahasia atau terbatas.

Batasan kualitas dan kompatibilitas

Konversi tidak selalu tanpa kehilangan. Atribut AsciiDoc, konten kondisional, include, custom role, macro, extension, tabel kompleks, admonition, dan cross-reference mungkin disederhanakan, dihilangkan, atau dihasilkan sebagai raw markup.

Periksa Markdown yang dihasilkan untuk memastikan level heading, nesting daftar, format tabel, path gambar, code fence, tautan, dan karakter yang di-escape. GFM mendukung tabel dan task list, tetapi parser Markdown lainnya mungkin merender fitur tersebut secara berbeda.

Include AsciiDoc mungkin memerlukan preprocessing sebelum konversi. Selesaikan file yang direferensikan oleh directive include::, dan periksa apakah path gambar dan tautan relatif masih mengarah ke lokasi yang benar setelah file output dipindahkan.