Pada tutorial ini, saya akan menjelaskan langkah-langkah menginstall Ruby di macOS dengan cara yang aman, lalu dilanjutkan dengan install Asciidoctor dan Asciidoctor PDF untuk generate file PDF dari format AsciiDoc.

Tutorial ini direkomendasikan untuk pengguna macOS yang ingin menulis dokumentasi, laporan, atau buku teknis dalam format PDF.

Pendahuluan

Secara default, macOS sudah memiliki Ruby bawaan sistem. Namun Ruby ini tidak disarankan untuk digunakan karena:

• Digunakan oleh sistem macOS
• Berpotensi konflik saat install gem
• Versinya sering tertinggal

Karena itu, pada tutorial ini Ruby akan diinstall menggunakan Homebrew, sehingga lebih aman dan mudah dikelola.

1. Install Homebrew

Homebrew adalah package manager di macOS yang digunakan untuk menginstall berbagai tools open source.

Jalankan perintah berikut di Terminal:

/bin/bash -c "$(curl -fsSL https://raw.githubusercontent.com/Homebrew/install/HEAD/install.sh)"

Setelah selesai, cek apakah Homebrew sudah terinstall:

brew --version

Jika versi Homebrew tampil, berarti instalasi berhasil.

2. Install Ruby Menggunakan Homebrew

Setelah Homebrew siap, langkah berikutnya adalah menginstall Ruby.

Install Ruby

brew install ruby

Tambahkan Ruby ke PATH

Agar Ruby yang digunakan adalah Ruby dari Homebrew (bukan Ruby bawaan macOS), tambahkan PATH berikut:

echo 'export PATH="/opt/homebrew/opt/ruby/bin:$PATH"' >> ~/.zshrc
source ~/.zshrc

Catatan:

• Untuk Mac Apple Silicon (M1/M2/M3) path biasanya /opt/homebrew
• Untuk Mac Intel biasanya /usr/local

Verifikasi Ruby

ruby -v

Jika versi Ruby yang tampil bukan system ruby, maka konfigurasi sudah benar.

3. Install Asciidoctor dan Asciidoctor PDF

Setelah Ruby terinstall dengan benar, kita bisa melanjutkan ke instalasi Asciidoctor.

Update RubyGems

gem update --system

Install Asciidoctor

gem install asciidoctor

Install Asciidoctor PDF

gem install asciidoctor-pdf

Cek versi

asciidoctor --version
asciidoctor-pdf --version

Jika perintah di atas menampilkan versi, berarti instalasi berhasil.

4. Cara Menggunakan Asciidoctor PDF

Misalnya terdapat file AsciiDoc bernama dokumen.adoc.

Untuk mengubahnya menjadi PDF, jalankan perintah berikut:

asciidoctor-pdf dokumen.adoc

Hasilnya akan otomatis menghasilkan file:

dokumen.pdf

5. Troubleshooting Umum

Perintah asciidoctor-pdf Tidak Ditemukan

Jika muncul error command not found, biasanya PATH gem belum dikenali.

Tambahkan PATH berikut:

export PATH="$(ruby -e 'puts Gem.user_dir')/bin:$PATH"

Lalu jalankan ulang:

asciidoctor-pdf --version

Penutup

Dengan mengikuti langkah-langkah di atas, Ruby dan Asciidoctor PDF dapat digunakan dengan aman di macOS tanpa mengganggu Ruby bawaan sistem. Setup ini cocok untuk kebutuhan dokumentasi teknis, laporan bulanan, maupun pembuatan buku dalam format PDF.