Belajar Zellij - Konfigurasi Dasar (config.kdl)

#Pendahuluan

Selama tujuh episode, kalian menekan tombol yang semuanya sudah terpasang default. Namun kalian tidak akan pernah menjadi pengguna Zellij yang benar-benar produktif jika tidak mulai menulis konfigurasi. Setiap orang punya tangan, editor, dan kebiasaan yang berbeda — dan Zellij memahami itu. Hampir semua perilaku yang kalian pelajari sejauh ini — keybinding, ukuran scrollback, perilaku mouse, plugin yang tampil di bar — berasal dari satu file: config.kdl. Di episode ini, file itu menjadi milik kalian.

Mengapa konfigurasi penting? Karena Zellij dirancang agar kunci ke kebiasaan kalian, bukan sebaliknya. Pilihan default Zellij bagus, tetapi bukan untuk semua orang. Mungkin kalian ingin Ctrl+b bergaya tmux, atau ingin scrollback lebih besar dari 10000 baris, atau ingin menonaktifkan mouse. Semua itu adalah keputusan yang ditulis sekali di config.kdl, disimpan di dotfiles, dan dibawa ke mana pun — termasuk ke server produksi. Inilah awal dari Zellij yang "milik kalian".

Peta episode: pertama kita temukan dan pahami struktur direktori konfigurasi. Lalu hasilkan file default dengan zellij setup --dump-config. Berikutnya tiga blok inti: keybinds, options, dan plugins. Terakhir, dua keterampilan operasional: reload konfigurasi tanpa restart dan menyimpan preferensi lewat Session mode. Pada akhir episode ini, config.kdl tidak lagi terasa seperti file misterius, melainkan papan kontrol Zellij.

Ada satu prinsip yang menyatukan semuanya: konfigurasi adalah kode. config.kdl adalah teks biasa yang bisa di-commit ke Git, di-review, diuji, dan disinkronkan antar mesin. Di episode 27 kita akan membungkus seluruhnya ke dalam dotfiles yang bisa di-bootstrap dalam satu perintah. Untuk sekarang, mulai dari satu file dan satu direktori — karena fondasi yang rapi menentukan seberapa jauh kalian bisa pergi.

#Lokasi dan Struktur Direktori Konfigurasi

Zellij mencari konfigurasi dalam urutan prioritas: file yang diberikan lewat flag --config, nilai variabel environment ZELLIJ_CONFIG_FILE, lalu lokasi default. Lokasi default mengikuti konvensi sistem operasi masing-masing. Di Linux (yang mengikuti standar XDG) konfigurasi berada di ~/.config/zellij/, dan di macOS di direktori Application Support. Windows mengikuti jalur %APPDATA% yang setara.

~/.config/zellij/
├── config.kdl
├── layouts/
│   └── (file layout .kdl, dibahas episode 10)
├── themes/
│   └── (file theme .kdl, dibahas episode 11)

~/Library/Application Support/com.Zellij-Contributors.zellij/
├── config.kdl
├── layouts/
└── themes/

Perhatikan dua hal. Pertama, bahasa konfigurasi Zellij adalah KDL — bukan YAML seperti tmux config klasik, bukan TOML. KDL terlihat seperti campuran XML dan bahasa pemrograman: node dipanggil dengan nama, diikuti kunci dan nilai. Strukturnya ringkas dan mudah dibaca. Kedua, folder layouts/ dan themes/ adalah direktori kerja Zellij: file .kdl di dalamnya akan dibahas di episode 10 (layouts) dan episode 11 (theme). Plugin WASM custom, sementara itu, dimuat dari lokasi mana pun yang kalian tunjuk dengan URL file:... — episode 15 akan membedahnya.

Bagi yang ingin fleksibilitas maksimal, ada ZELLIJ_CONFIG_DIR untuk mengganti direktori konfigurasi secara keseluruhan. Kombinasi ZELLIJ_CONFIG_FILE dan ZELLIJ_CONFIG_DIR membuat kalian bisa memiliki beberapa profil Zellij dan menukarnya sesuai konteks — satu untuk kerja lokal, satu untuk server.

Ketiga jalur penemuan konfigurasi — flag --config, environment, dan lokasi default — bekerja dalam urutan prioritas yang tegas. Flag menang atas segalanya, lalu ZELLIJ_CONFIG_FILE, lalu lokasi default. Ini sangat praktis untuk menguji: zellij --config /tmp/eksperimen.kdl menjalankan sesi dengan config sementara tanpa menyentuh config utama kalian. Begitu hasilnya cocok, salin ke tempat permanen dan jadikan bagian dari dotfiles.

#Menghasilkan config.kdl dengan zellij setup --dump-config

Dalam kebanyakan kasus, Zellij membuat config.kdl otomatis pada sesi pertama. Tetapi untuk memulai dengan fondasi yang lengkap — dan untuk mempelajari setiap opsi beserta komentarnya — cara terbaik adalah menghasilkan file default secara eksplisit.

mkdir -p ~/.config/zellij
zellij setup --dump-config > ~/.config/zellij/config.kdl

zellij setup --dump-config menulis seluruh konfigurasi default ke stdout — ratusan baris, lengkap dengan komentar penjelasan di setiap opsi. Dengan redirect ke config.kdl, kalian mendapatkan salinan lengkap yang siap diedit. Buka dengan editor kalian dan pelan-pelan hapus komentarnya seiring kalian memahami tiap bagian.

keybinds {
    normal { ... }
    resize { ... }
    pane { ... }
}
options { ... }
plugins { ... }

File hasil dump sangat berharga sebagai dokumentasi hidup. Setiap opsi diikuti komentar yang menjelaskan fungsi, nilai default, dan apakah ia membutuhkan restart. Alih-alih mengingat seluruh API konfigurasi, simpan file ini dan baca bagian yang relevan saat butuh. Menurut pedoman Zellij 0.44.x, urutan konfigurasi yang paling umum adalah: keybinds, lalu options, lalu plugins.

#Blok keybinds: Mengendalikan Setiap Mode

Blok keybinds adalah inti dari filosofi mode-based Zellij. Di dalamnya, setiap mode adalah sub-block, dan setiap baris bind menghubungkan satu atau lebih tombol dengan satu atau lebih aksi. Sintaksnya:

keybinds clear-defaults=true {
    normal {
        bind "Ctrl p" { SwitchToMode "Pane"; }
        bind "Alt n" { NewPane; }
        bind "Alt h" "Alt Left" { MoveFocusOrTab "Left"; }
    }
    pane {
        bind "x" { CloseFocus; SwitchToMode "Normal"; }
        bind "f" { ToggleFocusFullscreen; SwitchToMode "Normal"; }
    }
}

Dua hal kunci di sini. clear-defaults=true mengganti seluruh keybinding default dengan hanya apa yang kalian tulis — cara terbaik untuk memulai dari nol yang bersih. Tanpa flag itu, baris bind kalian menambah di atas default. Ada juga unbind untuk melepas tombol tertentu, dan unbind-all untuk mengosongkan satu mode. Masing-masing mode memiliki konteksnya sendiri: pane, tab, resize, move, scroll, session, tmux, dan locked.

Kekuatan tersembunyi ada di sintaks multi-key dan multi-action. bind "Alt h" "Alt Left" mengikat dua tombol sekaligus ke aksi yang sama — tidak perlu menulis dua baris. Dan satu tombol bisa memicu banyak aksi berurutan, seperti CloseFocus lalu SwitchToMode "Normal", persis seperti perilaku default saat menutup pane. Di episode 9 kalian akan membedah blok ini lebih dalam, termasuk menangani konflik antar keybinding.

Karena setiap mode punya block-nya sendiri, kalian bisa mengubah perilaku satu mode tanpa mengganggu yang lain. Ubah resize agar tombol h memperkecil alih-alih memperbesar? Cukup edit block resize — mode lain tidak tersentuh. Dan karena Zellij menampilkan hint keybinding di status-bar setiap kali kalian masuk mode, kalian bisa menguji keybind baru tanpa membuka manual. Siklus ubah-tes ini sangat singkat, terutama dengan reload otomatis yang dibahas di akhir episode ini.

#Blok options: Menyetel Perilaku Global

Jika keybinds menentukan tombol mana, options menentukan bagaimana Zellij berperilaku. Ini daftar opsi yang paling sering kalian ubah di awal:

options {
    scroll_buffer_size 50000
    copy_command "wl-copy"
    mouse_mode true
    pane_frames true
}

Perhatikan sintaks KDL di blok ini: nama opsi diikuti nilai, tanpa tanda sama dengan dan tanpa titik koma. scroll_buffer_size 50000 menaikkan memori scrollback dari 10000 menjadi 50000 baris per pane — berguna untuk log yang panjang, dengan harga memori yang lebih besar. copy_command "wl-copy" menggantikan protokol OSC 52 dengan perintah Wayland yang sudah kalian kenal di episode 6. pane_frames false menyembunyikan frames secara permanen — keputusan estetika yang juga bisa dilakukan sesaat lewat Ctrl+p lalu z.

Dua opsi yang paling sering menimbulkan kejutan. mouse_mode false menyelesaikan konflik salin-tempel di terminal tertentu (beberapa terminal kesulitan menyeleksi teks saat mode mouse aktif), tetapi kalian kehilangan resize via drag dan scroll mouse. Dan scroll_buffer_size bukan opsi yang "semakin besar semakin baik" tanpa biaya — setiap pane menyimpan buffer di memori, jadi ratusan ribu baris dikali puluhan pane bisa terasa. Mulai dari 50000 dan naikkan hanya jika perlu.

#Blok plugins: Antarmuka yang Kalian Lihat Setiap Hari

Banyak yang tidak menyadari bahwa tab-bar di atas, status-bar di bawah, dan strider adalah plugin — modul WASM yang berjalan di dalam Zellij. Blok plugins menentukan plugin mana yang dimuat dan di mana. Ini bagian yang kalian lihat setiap detik, meskipun jarang kalian sentuh.

plugins {
    tab-bar location="zellij:tab-bar"
    status-bar location="zellij:status-bar"
    strider location="zellij:strider"
    compact-bar location="zellij:compact-bar"
}

Empat plugin bawaan membentuk antarmuka: tab-bar (daftar tab di atas), status-bar (bar bawah dengan mode dan hint), strider (file explorer, episode 14), dan compact-bar (versi ringkas status-bar). URL zellij:... adalah alias untuk plugin bawaan; kalian bisa mengganti location dengan file:/path/to/plugin.wasm atau https://... untuk plugin custom — fondasi yang akan kalian bangun di episode 15 dan 16. Ada juga blok load_plugins untuk memuat plugin di latar belakang saat sesi dimulai.

Mengganti plugin bawaan adalah cara paling populer untuk mengubah tampilan Zellij tanpa menyentuh kode. Ingin status-bar yang lebih ringkas? Arahkan status-bar location ke plugin compact-bar atau custom. Ingin tab-bar dengan informasi tambahan? Ganti tab-bar location dengan plugin buatan komunitas. Karena Zellij memperlakukan antarmuka sebagai plugin, kalian mendapatkan tingkat kustomisasi yang tidak dimiliki multiplexer tradisional — dan episode 15 akan menunjukkan cara menulis plugin kalian sendiri.

#Reload Tanpa Restart dan Menyimpan Preferensi

Salah satu fitur yang paling menyenangkan sejak Zellij 0.41: konfigurasi di-reload secara otomatis. Zellij memasang file-watcher pada config.kdl aktif. Ubah file, simpan, dan sebagian besar perubahan langsung diterapkan pada sesi yang berjalan — keybinding baru aktif dalam hitungan detik, tema berganti di depan mata. Tidak ada Ctrl+r, tidak ada restart, tidak ada detach-attach.

Reload otomatis bekerja lewat file-watcher yang memantau config.kdl setiap detik. Artinya, editor dengan auto-save akan memicu reload bahkan tanpa kalian menekan save secara eksplisit — dan file yang dihapus sementara akan ditunggu hingga muncul kembali. Satu catatan kecil: karena watcher bekerja pada file langsung, config yang berupa symlink (misalnya dari dotfiles manager seperti stow) bisa tidak terdeteksi pada versi tertentu — salin file secara fisik jika kalian mengalami hal ini.

Namun tidak semua opsi bisa di-reload dengan cara ini. Opsi yang memengaruhi arsitektur — misalnya default_mode, session_serialization, atau layout_dir — ditandai Requires restart di komentar config.kdl. Untuk opsi seperti itu, kalian harus memulai sesi baru (atau me-restart sesi lama). Kebiasaan yang benar: cek komentar opsi sebelum berharap perubahan langsung berlaku.

Cara kedua untuk mengubah preferensi adalah lewat Session mode. Tekan Ctrl+o, lalu c untuk membuka layar Configuration. Di sinilah kalian bisa mengganti preset keybinding (termasuk mode non-colliding), mengganti secondary modifier, dan menyetel opsi tanpa menyentuh file. Perubahan bisa diterapkan ke sesi berjalan atau disimpan ke config.kdl agar persisten — perbedaannya hanya satu langkah di layar itu. Sementara itu, Ctrl+o lalu w membuka session-manager untuk mengelola banyak sesi.

zellij action save-session

Zellij menyerialisasi sesi secara berkala untuk keperluan resurrection. zellij action save-session memicu serialisasi seketika — berguna ketika kalian baru saja merombak tata letak dan ingin memastikan state itu tersimpan sebelum menutup sesi. Detail resurrection akan dibahas di episode 17; untuk sekarang, ingat bahwa preferensi kalian punya jalur penyimpanan: config file untuk permanen, Session mode untuk interaktif.

#Kesalahan Umum (Common Pitfalls)

1. Mengira KDL adalah YAML. key: value dan indentasi gaya YAML tidak berlaku. Sintaks KDL adalah node key=value tanpa titik dua. Mencampur keduanya membuat parser gagal — pelajari bentuk KDL sekali, dan selesai.
2. Melupakan clear-defaults=true. Tanpa flag ini, keybind custom kalian hanya menambah default — dan konflik tersembunyi bisa membuat tombol tidak berfungsi seperti harapan. Jika ingin kontrol penuh, mulai dengan keybinds clear-defaults=true.
3. Mengharapkan semua opsi bisa reload langsung. Opsi berlabel Requires restart tidak akan aktif sampai sesi dimulai ulang. Ubah harapan kalian sesuai komentar di file.
4. Menulis copy_command untuk platform yang salah. Konfigurasi yang berisi pbcopy di Linux tidak akan bekerja. Jaga config.kdl tetap portabel dengan menyesuaikan perintah clipboard per mesin, atau simpan profil terpisah via ZELLIJ_CONFIG_FILE.
5. Mengabaikan Session mode sebagai alat konfigurasi. Banyak opsi bisa diubah interaktif lewat Ctrl+o lalu c tanpa menyentuh file. Ini cara tercepat untuk mengetes preset keybinding sebelum memutuskan menuliskannya permanen.

#Penutup

Kalian kini memiliki kunci Zellij: tahu di mana config berada, cara menghasilkan versi default, dan cara membaca serta menulis tiga blok utamanya. keybinds mengendalikan tombol, options mengendalikan perilaku, plugins mengendalikan antarmuka. Ditambah kemampuan reload tanpa restart dan penyimpanan preferensi lewat Session mode, kalian tidak lagi bergantung pada pengaturan pabrik — Zellij mulai menyesuaikan diri dengan kalian, bukan sebaliknya.

Poin yang harus kalian bawa:

• Konfigurasi di ~/.config/zellij/config.kdl, bahasa KDL.
• Generate default dengan zellij setup --dump-config > config.kdl.
• Tiga blok inti: keybinds, options, plugins.
• Perubahan config di-reload otomatis; opsi Requires restart butuh sesi baru.
• Session mode (Ctrl+o lalu c) untuk konfigurasi interaktif; save-session untuk serialisasi seketika.

Di episode 9 berikutnya, kita menyelami blok keybinds lebih dalam: custom keybindings dan keybinding conflicts. Kalian akan belajar sintaks bind/unbind per mode, clear-defaults dan unbind-all, multi-action dalam satu keybind, hingga strategi menyelesaikan konflik antara Zellij, shell, dan editor kalian. Sampai jumpa di episode 9.