Editor

Introduction

Editor web adalah antarmuka visual untuk membuat, mengedit, dan meninjau dokumentasi langsung di browser Anda.

Editor web menawarkan pengalaman What-You-See-Is-What-You-Get (WYSIWYG) sambil mempertahankan sinkronisasi dengan repositori Git Anda, yang memungkinkan Anda melihat pembaruan secara real-time dan berkolaborasi dengan tim Anda pada perubahan dokumentasi.

Editor web vs. CLI

Editor web memungkinkan Anda menulis dan mengedit dokumentasi Anda di browser tanpa memerlukan alat pengembangan lokal atau menggunakan baris perintah. Anda sebaiknya menggunakan editor web jika Anda ingin memelihara dokumentasi Anda di satu tempat dengan satu alat.

CLI adalah alat baris perintah yang memungkinkan Anda membuat dan mengelola dokumentasi Anda secara lokal menggunakan IDE pilihan Anda. Anda sebaiknya menggunakan CLI jika Anda ingin mengintegrasikan dokumentasi ke dalam alur kerja pengembangan yang sudah ada.

Baik editor web maupun CLI sepenuhnya terintegrasi dengan repositori Git Anda, sehingga Anda dapat menggunakannya secara bergantian dan anggota tim yang berbeda dapat menggunakan salah satu alat berdasarkan preferensi mereka.

Mode Editor

Editor web menawarkan dua mode untuk mengakomodasi preferensi dan kebutuhan pengeditan yang berbeda.

Anda dapat beralih antara mode alami kapan saja menggunakan toggle di pojok kanan atas toolbar editor.

Mode Visual

Mode visual menyediakan pengalaman WYSIWYG di mana perubahan yang Anda buat di editor adalah perubahan yang akan dipublikasikan ke situs dokumentasi Anda. Mode ini ideal ketika Anda ingin melihat bagaimana perubahan Anda akan terlihat secara real-time.

Menu Komponen

Anda dapat menambahkan blok konten dan komponen lain ke dokumentasi Anda dalam mode visual menggunakan menu komponen dropdown.

1. Tekan tombol / untuk membuka menu komponen.
2. Pilih komponen dari menu.

Mode Markdown

Mode Markdown memberikan akses langsung ke kode MDX yang mendasari dokumentasi Anda. Mode ini lebih disukai ketika Anda memerlukan kontrol yang tepat atas properti komponen atau ketika Anda lebih suka menulis dalam sintaks Markdown/MDX.

Membuat Perubahan

1. Jelajahi file: Gunakan penjelajah file sidebar untuk menavigasi melalui dokumentasi Anda.
2. Buka file: Klik pada file yang ingin Anda edit untuk membukanya di editor.
3. Buat perubahan: Edit konten menggunakan mode visual atau Markdown. Perubahan secara otomatis disimpan sebagai draf.
4. Pratinjau perubahan: Lihat bagaimana perubahan Anda akan muncul dalam mode visual.

Publikasi

Publikasi langsung memperbarui cabang deployment yang dikonfigurasi. Untuk alur kerja kolaboratif, pertimbangkan untuk menggunakan cabang dan pull request sebagai gantinya.

Ketika Anda siap untuk membuat perubahan Anda aktif, klik tombol Publish di pojok kanan atas editor web.

Perubahan Anda akan segera diterapkan ke situs produksi Anda.

Branches

Branches memungkinkan Anda bekerja pada perubahan dokumentasi tanpa memperbarui versi utama sampai Anda siap untuk perubahan Anda diterapkan.

Gunakan branches untuk pembaruan signifikan, bagian baru, atau ketika beberapa anggota tim sedang bekerja pada bagian dokumentasi yang berbeda secara bersamaan.

Membuat Branch

1. Pilih nama branch di toolbar editor (biasanya main secara default).
2. Pilih New Branch.
3. Masukkan nama deskriptif untuk branch Anda.
4. Pilih Create Branch.

Beralih Branch

1. Pilih nama branch saat ini di toolbar editor.
2. Pilih branch yang ingin Anda alihkan dari menu dropdown.

Menyimpan Perubahan pada Branch

Untuk menyimpan perubahan Anda pada branch, pilih tombol Save Changes di pojok kanan atas editor.

Ketika Anda sedang bekerja pada sebuah branch, perubahan Anda tidak secara otomatis disimpan.

Pull Requests

Pull requests (atau PR) memungkinkan Anda dan orang lain untuk meninjau perubahan yang telah Anda buat pada sebuah branch dan kemudian menggabungkan perubahan tersebut ke dalam dokumentasi utama Anda.

Membuat Pull Request pada Sebuah Branch

1. Buat perubahan Anda pada sebuah branch.
2. Klik tombol Publish Pull Request di pojok kanan atas editor.
3. Tambahkan Judul Pull Request dan Deskripsi untuk pull request Anda. Judul dan deskripsi yang baik akan membantu para peninjau memahami perubahan yang telah Anda buat.
4. Klik Publish Pull Request.

Meninjau Pull Requests

Anda dapat meninjau pull requests di platform Git Anda (GitHub, GitLab).

Setelah Anda membuat pull request, Anda dapat melihat pratinjau deployment dari perubahan tersebut.

Setelah seorang peninjau menyetujui pull request, Anda dapat menggabungkan pull request tersebut ke dalam branch utama Anda dan perubahan akan di-deploy ke situs dokumentasi live Anda.

Sinkronisasi Git

Editor web terintegrasi dengan repositori Git Anda, memastikan bahwa semua perubahan diverifikasi dan dilacak dengan benar.

Bagaimana Sinkronisasi Git Bekerja

• Autentikasi: Editor web terhubung ke repositori Git Anda melalui GitHub App atau GitLab integration.

• Pengambilan otomatis: Ketika Anda membuka editor, secara otomatis mengambil konten terbaru dari branch utama repositori Anda.

• Pelacakan perubahan: Saat Anda membuat pengeditan, editor web melacak perubahan dan dapat melakukan commit ke repositori Anda.

• Branching: Anda dapat membuat perubahan langsung ke branch utama Anda atau ke branch terpisah, tergantung pada preferensi alur kerja Anda.

• Pull requests: Untuk alur kerja kolaboratif, Anda dapat membuat pull requests dari editor web.

Terminologi Git

Memahami istilah-istilah berikut dapat membantu Anda bekerja lebih efektif dengan editor web dan alur kerja Git.

Repository

Sebuah repository (atau repo) adalah tempat file dokumentasi Anda disimpan, bersama dengan riwayat revisinya. Editor web terhubung ke repositori Git Anda untuk mengambil dan menyimpan konten dokumentasi.

Commit

Sebuah commit adalah snapshot perubahan pada dokumentasi Anda pada titik waktu tertentu. Ketika Anda mempublikasikan perubahan di editor web, Anda sedang membuat commit di repositori Git Anda.

Branch

Sebuah branch adalah versi paralel dari dokumentasi Anda yang memungkinkan Anda untuk bekerja pada perubahan tanpa mempengaruhi versi utama. Editor web memungkinkan Anda untuk membuat dan beralih antar branch.

Pull Request

Sebuah pull request (atau PR) adalah proposal untuk menggabungkan perubahan dari satu branch ke branch lain, biasanya dari branch fitur ke branch utama. PR memfasilitasi peninjauan dan diskusi sebelum perubahan dimasukkan.

Diff

Sebuah diff (atau perbedaan) menunjukkan perubahan spesifik antara dua versi file. Ketika meninjau pull requests, diff menyoroti apa yang telah ditambahkan, dihapus, atau dimodifikasi.

Pemecahan Masalah

Berikut adalah solusi untuk masalah umum yang mungkin Anda hadapi dengan editor web.

Perubahan Tidak Muncul Setelah Publikasi

Kemungkinan penyebab:

• Deployment masih dalam proses
• Masalah caching di browser Anda

Solutions:

1. Periksa status deployment di Dashboard Mintlify Anda.
2. Coba refresh keras browser Anda (Ctrl+F5 atau Cmd+Shift+R).
3. Bersihkan cache browser Anda.

Error Izin Saat Publikasi

Kemungkinan penyebab:

• Izin tidak cukup untuk repositori Git
• Masalah autentikasi dengan penyedia Git Anda

Solutions:

1. Verifikasi bahwa Anda memiliki akses yang benar ke repositori.
2. Periksa apakah integrasi Git Anda dikonfigurasi dengan benar.
3. Tinjau dokumentasi Editor Permissions.

Masalah Pemuatan Editor

Kemungkinan penyebab:

• Masalah konektivitas jaringan
• Repositori dokumentasi yang besar

Solutions:

1. Periksa koneksi internet Anda.
2. Segarkan halaman dan coba lagi.
3. Hubungi dukungan jika masalah berlanjut.