README GitHub diubah menjadi PDF dengan menyalin isi mentah berkasnya, lalu menempelkannya ke Markdown ke PDF. Berkas README memang ditulis dalam Markdown, jadi penandanya sudah cocok dengan tool itu tanpa perlu diubah. Hasilnya dokumen A4 dengan margin 20 mm dan teks 11 pt.
Halaman GitHub menampilkan README dalam bentuk yang sudah dirender: judul menjadi besar, tabel menjadi rapi, dan lencana tampil sebagai gambar. Tampilan itu hanya ada selama halamannya dibuka. Begitu berkasnya diunduh dan dibaca di luar GitHub, isinya kembali menjadi teks Markdown apa adanya. Mengompilasinya menjadi PDF membuat tampilan itu ikut terbawa ke dalam berkas yang bisa dikirim dan dibaca tanpa koneksi.
Satu hal yang perlu diketahui sejak awal: lencana, tangkapan layar, dan gambar lain yang ditulis sebagai tautan luar tidak ikut tercetak. Yang muncul adalah keterangan [Gambar: alt] di posisi gambar itu ditulis. Bagian di bawah menjelaskan cara menyikapinya.
Kapan README perlu dijadikan PDF
Ada beberapa situasi yang membuat README lebih berguna sebagai PDF. Yang paling sering: dokumentasi proyek perlu dilampirkan ke laporan atau berkas pengajuan yang hanya menerima PDF. Penerimanya tidak akan membuka repositori, jadi dokumennya harus berdiri sendiri.
Situasi lain: dokumentasi perlu ditinjau oleh orang yang tidak memakai GitHub, misalnya peninjau internal atau klien. PDF memastikan mereka membaca versi yang sama, bukan versi yang sudah berubah karena ada komit baru. Berkas PDF adalah potret naskah pada saat kompilasi dijalankan.
Sebaliknya, jangan jadikan PDF sebagai satu-satunya salinan dokumentasi. PDF tidak bisa disunting senyaman berkas Markdown, dan setiap perubahan di repositori tidak otomatis masuk ke berkas PDF-nya. Sumbernya tetap README, dan PDF hanya bentuk kirimannya.
Langkah membuat PDF dari README GitHub
- Buka halaman repositori di GitHub, lalu buka berkas README-nya.
- Klik tombol Raw untuk melihat naskah mentahnya. Tampilan Raw memuat penanda Markdown yang belum dirender.
- Salin seluruh isi halaman Raw.
- Buang lencana di bagian atas. Baris lencana biasanya berupa tautan yang membungkus gambar, dan tidak ada gunanya di dokumen cetak.
- Periksa blok kode dan tabelnya. Pastikan pagar blok kode berpasangan dan setiap baris tabel punya jumlah kolom yang sama.
- Buka Markdown ke PDF, lalu tempelkan naskahnya.
- Jalankan prosesnya, unduh hasilnya, lalu periksa bagian awal dan bagian yang memuat tabel.
Langkah keempat dan kelima menentukan seberapa bersih hasilnya. Lencana yang dibiarkan akan tercetak sebagai deretan keterangan gambar yang tidak informatif, dan blok kode yang pagarnya tidak berpasangan akan membingungkan mesin render.
Lencana, gambar, dan tautan di dalam README
README proyek hampir selalu memuat lencana di bagian atas: gambar kecil yang menaut ke halaman lain. Di dokumen cetak, lencana ini kehilangan fungsinya karena tidak bisa diklik, dan gambarnya sendiri tidak dimuat oleh tool ini. Yang tercetak adalah keterangan seperti [Gambar: build passing]. Membuang barisnya sebelum kompilasi membuat dokumen lebih rapi.
Gambar dari tautan luar juga tidak dimuat, termasuk diagram dan tangkapan layar yang biasanya ditulis sebagai tautan ke repositori. Keterangan [Gambar: alt] tetap tercetak, jadi pembaca tahu ada gambar di posisi itu. Kalau gambarnya memang harus ikut, jalur yang tepat adalah HTML Pro ke PDF: gambar dari URL publik HTTPS diunduh dan ikut dicetak.
Tautan dicetak sebagai teks diikuti alamatnya di dalam tanda kurung, misalnya dokumentasi (https://contoh.com/docs). Untuk README yang isinya banyak merujuk ke halaman lain, bagian akhir dokumen akan terlihat padat. Pertimbangkan memindahkan daftar rujukan ke satu bagian tersendiri sebelum dikompilasi.
Tautan relatif di dalam README, misalnya menuju berkas lain di repositori yang sama, juga tercetak sebagai alamat relatif. Alamat itu tidak bisa dibuka dari dokumen cetak, jadi tulis ulang sebagai alamat lengkap kalau pembacanya perlu menelusuri sendiri.
HTML di dalam README
README GitHub mengizinkan sebagian penanda HTML, dan banyak proyek memakainya untuk menyusun tabel atau menyelaraskan gambar. Penanda itu tidak dirender oleh tool Markdown ini. Yang tercetak adalah teks di dalamnya, atau penandanya ikut terlihat sebagai teks biasa.
Kalau README Anda bergantung pada HTML untuk susunannya, ada dua pilihan yang jujur. Pertama, ubah susunannya menjadi penanda Markdown standar sebelum dikompilasi: tabel Markdown untuk data tabular, dan judul untuk pemisahan bagian. Kedua, pindah ke jalur HTML kalau susunannya memang memerlukan markup.
Perlu diingat bahwa tabel Markdown punya batas: sel yang panjang dipotong menjadi beberapa baris supaya tabelnya tidak melewati tepi halaman. Tabel yang di GitHub tampil rapi karena halamannya bisa digulir mendatar akan terlihat berbeda di dokumen cetak, karena kertas tidak bisa digulir.
Blok kode dan perintah
README teknis hampir selalu memuat blok kode: perintah pemasangan, contoh pemakaian, dan potongan konfigurasi. Blok kode ditata dengan huruf monospace supaya sejajar, dan perataan itu yang membuatnya terbaca.
Baris kode yang sangat panjang tidak dibungkus dan bisa melewati tepi halaman. Periksa perintah yang panjang di naskah Anda, lalu pecah menjadi beberapa baris dengan penanda lanjutan yang sesuai dengan shell-nya. Perbaikan di naskah sumber jauh lebih cepat daripada memperbaiki tata letak di berkas PDF.
Pagar blok kode harus berpasangan. Pagar pembuka tanpa penutup akan membuat seluruh isi setelahnya dianggap bagian dari kode, dan itu mengubah tampilan dokumen sampai akhir. Kalau hasil kompilasi tiba-tiba berubah menjadi monospace di tengah dokumen, periksa pagar kodenya.
Pemisah halaman untuk dokumentasi
Pemisah halaman ditulis dengan baris berisi tiga tanda hubung. Baris itu tidak ikut tercetak, dan isi setelahnya dimulai di halaman baru. Untuk dokumentasi proyek, penanda ini berguna untuk memisahkan bagian yang memang berbeda topik, misalnya pemasangan dan contoh pemakaian.
Penomoran halaman tidak diatur dari naskah. Kalau dokumennya memerlukan nomor halaman, atur setelah berkas PDF-nya jadi, atau gunakan jalur HTML Pro yang bisa menulis aturan cetaknya sendiri di CSS. Markdown memakai lembar A4 dengan margin 20 mm, tanpa pilihan ukuran kertas atau margin.
Masalah yang sering terjadi
Lencana tercetak sebagai teks panjang. Penyebabnya baris lencana tidak dibuang sebelum kompilasi. Buang barisnya di naskah, karena gambar dari tautan luar tidak dimuat oleh tool ini.
Tabel berantakan. Penyebabnya jumlah kolom tidak sama antar baris, atau baris judul tabelnya tidak memakai penanda tanda hubung. Periksa tabelnya di naskah mentah, bukan di tampilan GitHub yang sudah dirender.
Seluruh isi setelah satu titik menjadi monospace. Penyebabnya pagar blok kode yang tidak ditutup. Cari pagar pembuka tanpa pasangan, lalu tutup dengan tiga tanda backtick.
Tautan relatif tidak bisa dibuka. Tautan relatif tercetak sebagai alamat relatif yang hanya berarti di dalam repositori. Tulis ulang sebagai alamat lengkap kalau pembacanya perlu membukanya.
Hasilnya lebih panjang dari perkiraan. Sel tabel yang panjang dipotong menjadi beberapa baris, dan setiap potongan menambah tinggi. Sederhanakan tabel terpanjang atau pindahkan sebagian isinya ke daftar biasa.
Kapan sebaiknya tidak memakai tool daring
README yang memuat kredensial, alamat server internal, atau catatan konfigurasi yang belum boleh keluar dari jaringan kantor sebaiknya dikompilasi dengan aplikasi yang berjalan di komputer sendiri. Untuk tool di katalog ini, berkas dialirkan ke pemroses dan hasilnya dikirim balik ke peramban tanpa ditulis ke penyimpanan permanen, tetapi berkas tetap meninggalkan perangkat selama proses berlangsung. Keterangan lengkapnya ada di kebijakan privasi.
Batas paketnya: tanpa akun 20 pemrosesan per hari dengan 10 MB per berkas, paket Gratis 30 pemrosesan per hari, dan paket Berbayar tanpa batas jumlah pemrosesan dengan 200 MB per berkas. Rinciannya ada di halaman harga.
Pertanyaan yang sering muncul
Apakah README bisa diunduh langsung dari GitHub lalu diunggah? Tool ini bekerja dari teks yang ditempelkan, jadi isi berkasnya perlu disalin lebih dulu. Halaman Raw adalah tempat paling mudah untuk menyalin naskah mentahnya.
Apakah lencana proyek ikut tercetak? Tidak. Lencana adalah gambar dari tautan luar, dan tool ini tidak memuat gambar jenis itu. Yang tercetak adalah keterangan gambar, dan itu sebabnya lencana sebaiknya dibuang sebelum kompilasi.
Bagaimana cara menampilkan diagram yang ada di repositori? Jalur Markdown tidak memuat gambar dari tautan luar. Kalau diagramnya harus ikut, susun dokumennya sebagai HTML dan gunakan jalur HTML Pro, yang mengunduh gambar dari URL publik HTTPS.
Apakah isi README yang sudah dirender di GitHub bisa disalin langsung? Bisa, tetapi hasilnya kehilangan penanda Markdown: judul dan tabelnya menjadi teks biasa. Menyalin dari halaman Raw mempertahankan penandanya.
Apakah hasil PDF-nya bisa disunting lagi? Bisa dibuka di aplikasi penyunting PDF, tetapi tidak senyaman menyunting naskah Markdown-nya. Kalau ada yang perlu diperbaiki, sunting README-nya lalu kompilasi ulang.
Setelah dokumentasi menjadi PDF
Periksa bagian awal, tabel, dan blok kodenya. Kalau ada halaman kosong di antara dua bagian, periksa penanda pemisah halamannya. Kalau dokumennya perlu disatukan dengan berkas lain, gunakan Gabung PDF, dan kalau ukurannya perlu dikecilkan, gunakan Kompres PDF. Pekerjaan merapikan halaman dibahas di Mengatur Halaman PDF.
Buka Markdown ke PDF, tempelkan naskah README-nya, lalu kompilasi. Peta lengkap kelompok ini ada di Membuat PDF dari Gambar, Teks, dan Halaman Web.