Mengorganisir Proyek Markdown

Organisasi yang baik membuat proyek Markdown lebih mudah dipelihara, dinavigasi, dan dikembangkan. Baik Anda mengelola dokumentasi untuk proyek software, buku, atau perpustakaan konten, struktur yang tepat menghemat waktu dan mencegah sakit kepala.

Panduan ini mencakup praktik terbaik untuk mengorganisir file dan proyek Markdown.

Konvensi Penamaan File

Gunakan Nama Deskriptif

Beri nama file berdasarkan kontennya, bukan pengenal sembarang:

# Baik
getting-started.md
api-reference.md
troubleshooting-guide.md

# Hindari
doc1.md
chapter_final_v2_FINAL.md

Huruf Kecil dengan Tanda Hubung

Gunakan huruf kecil dan tanda hubung untuk kompatibilitas di semua sistem:

# Baik
user-authentication.md

# Hindari
User_Authentication.md

Struktur Folder

Proyek Dokumentasi

docs/
├── README.md
├── getting-started/
│   ├── installation.md
│   ├── configuration.md
│   └── quick-start.md
├── guides/
│   ├── user-guide.md
│   └── admin-guide.md
├── reference/
│   ├── api.md
│   └── cli.md
└── assets/
    └── images/

Buku atau Konten Panjang

book/
├── README.md
├── 01-introduction/
│   ├── chapter.md
│   └── images/
├── 02-fundamentals/
│   ├── chapter.md
│   └── images/
└── appendix/
    └── glossary.md

Praktik Terbaik

Satu Topik Per File

Jaga setiap file tetap fokus pada satu topik. Lebih mudah menemukan, mengedit, dan menggunakan kembali konten saat tidak tersembunyi dalam dokumen besar.

Gunakan README di Root

Buat README.md di root proyek yang menyediakan gambaran umum dan navigasi ke dokumen lain.

Pisahkan Aset

Simpan gambar dan aset lainnya di folder khusus. Gunakan path relatif untuk mereferensikannya:

![Diagram](./assets/images/architecture.png)

File Indeks

Dalam proyek yang lebih besar, tambahkan file indeks atau gambaran umum di setiap folder:

guides/
├── README.md  # Gambaran umum semua panduan
├── user-guide.md
└── admin-guide.md

Tips Version Control

• .gitignore - Kecualikan file yang dihasilkan (PDF, HTML) jika Anda menghasilkannya ulang
• Commit yang bermakna - Tulis pesan commit yang jelas untuk perubahan dokumentasi
• Branching - Gunakan branch untuk pembaruan dokumentasi besar
• Pull request - Tinjau perubahan dokumentasi seperti kode

Mengonversi Proyek yang Terorganisir

Proyek yang terorganisir dengan baik membuat konversi batch menjadi mudah:

1. Navigasi ke folder dokumen Anda
2. Pilih file yang perlu dikonversi
3. Gunakan konversi batch untuk memproses semuanya
4. Unduh ZIP dengan file yang telah dikonversi yang mempertahankan struktur Anda

Panduan Terkait

• Alur Kerja Markdown untuk Penulis Teknis - Alur kerja lengkap
• Konversi Batch File Markdown - Proses beberapa file
• Markdown untuk Dokumentasi Software - Praktik terbaik dokumentasi dev