Buat modul dokumentasi baru
Bagian ini menjelaskan cara menambahkan dokumen baru yang sepenuhnya mencakup area baru secara keseluruhan. Dokumen ini mencakup beberapa halaman dan biasanya terkait dengan pembuatan repositori baru yang khusus. Lingkungan kerja lokal paling cocok untuk ini. Namun, juga dimungkinkan untuk menggunakan web IDE dari berbagai platform GIT.
Sebelum Anda mulai mengikuti prosedur ini, periksa semua persyaratan yang tercantum di Persyaratan.
Konfigurasi repositori dokumentasi
| Meskipun Anda dapat membuat repositori baru atau menggunakan repositori yang sudah ada, kami menyarankan untuk memulai dari repositori templat yang disediakan jika Anda belum familiar dengan Antora. |
Buat repositori baru untuk set dokumentasi baru, atau mintalah seseorang untuk membuatnya untuk Anda. Anda dapat menghosting repositori ini di mana saja, tetapi kami merekomendasikan menggunakan GitLab di mana Anda dapat menggunakan grup Fedora untuk mengontrol akses tulis ke repositori. Tergantung pada topiknya, mungkin lebih baik menghostingnya di bawah ruang nama Fedora Docs.
Di GitLab, Anda dapat menggunakan New project > Create from template > Group dan pilih Documentation Template dalam daftar.
Jika Anda tidak menggunakan GitLab, kloning template repository secara manual dan salin isinya ke repositori baru Anda.
📄 antora.yml
📄 site.yml
📂 modules
📂 ROOT
📄 nav.adoc
📂 pages
📄 index.adoc
📄 another-page.adoc
Di repositori baru, edit berkas konfigurasi antora.yml di akar repositori. Berkas tersebut berisi komentar yang menandai bagian-bagian yang perlu diubah. Setidaknya, selalu ubah nilai name dan title.
Nama (name) adalah yang akan menentukan URL akhir dokumentasi Anda. Contoh: docs.fedoraproject.org/en-US/<name>/
|
Selain itu, edit berkas konfigurasi site.yml. Perlu diingat bahwa berkas ini hanya digunakan saat membangun pratinjau lokal dari kumpulan konten Anda - di situs web, berkas ini akan digantikan oleh berkas konfigurasi site.yml yang berlaku secara global. Satu-satunya pengaturan yang perlu Anda edit dalam berkas ini adalah title dan start_page.
Pada tahap ini, konfigurasi awal telah selesai. Anda dapat mengunggah perubahan ini ke repositori yang baru dibuat (atau mengajukan permintaan pull jika Anda tidak memiliki hak akses yang diperlukan) dan mulai bekerja pada penulisan dokumentasi sebenarnya.
Menulis dokumentasi
Beberapa tautan dokumentasi yang berguna:
Jika dokumentasi Anda terdiri dari beberapa halaman, Anda dapat mencantumkannya dalam berkas nav.adoc. Berkas ini akan digunakan untuk membangun menu navigasi di sisi kiri dokumen docs.fp-o.
Saat Anda sedang menulis, Anda dapat menggunakan local preview untuk memeriksa dokumen yang dihasilkan.
Menerbitkan modul dokumentasi baru
Setelah repositori disiapkan dan konten awal ditambahkan, repositori siap untuk dipublikasikan.
Modul dokumentasi yang diterbitkan di docs.fp-o semuanya terdaftar dalam main Antora playbook.
Untuk menambahkan modul dokumentasi baru, Anda perlu menambahkan repositori modul tersebut ke daftar content.sources:
content:
sources:
- url: https://gitlab.com/path/to/new/repository.git
branches: main (1)
start_path: docs (2)
| 1 | Cabang default diatur ke master. Jika repositori Anda menggunakan nama lain (seperti main), Anda perlu menentukannya di sini. <.> Pengaturan ini bersifat opsional. Jika berkas dokumentasi disimpan dalam subdirektori di repositori Anda (misalnya /docs/), Anda harus menetapkan jalur relatifnya di sini, tanpa tanda garis miring di awal atau akhir. Jika berkas tersebut berada di tingkat akar, seperti yang dijelaskan di halaman ini, Anda dapat mengabaikan parameter ini. |
Anda dapat membuat Merge Request dengan perubahan ini, atau jika Anda tidak merasa nyaman mengedit berkas ini, buatlah tiket di repositori Fedora Docs Website, dan Tim Dokumentasi akan menangani bagian tersebut untuk Anda.
|
Jika Anda tidak menerima pembaruan apa pun untuk Merge Request atau tiket Anda setelah 5 hari, hubungi Tim Dokumen. |
Want to help? Learn how to contribute to Fedora Docs ›