Apidog

Platform Pengembangan API Kolaboratif All-in-one

Desain API

Dokumentasi API

Debug API

Mocking API

Pengujian Otomatis

Daftar gratis
UnduhUntuk Mac atau Linux
Home

/

Apa itu MkDocs? Cara Install, Menggunakan, dan Deploy MkDocs

Apa itu MkDocs? Cara Install, Menggunakan, dan Deploy MkDocs

Ashley Goolam

Ashley Goolam

Updated on May 19, 2025

Ingin membuat dokumen API yang rapi dan profesional tanpa bersusah payah dengan alat yang rumit? Sambutlah MkDocs, generator situs statis yang cepat dan sederhana yang mengubah file Markdown Anda menjadi situs dokumentasi yang indah. Saya sudah mencoba MkDocs untuk membuat dokumen API, dan percayalah—ini sangat mudah baik untuk pemula maupun profesional. Dalam panduan pemula ini, saya akan memandu Anda melalui apa itu MkDocs, cara menginstalnya, menggunakannya untuk membangun dokumentasi API, dan menyebarkannya ke GitHub Pages, semuanya berdasarkan langkah-langkah resmi. Selain itu, saya akan sedikit menyinggung Dokumentasi APIdog sebagai alternatif yang lebih mewah. Siap membuat dokumen API Anda bersinar? Mari kita mulai!

button

Apa Itu MkDocs? Pengantar Singkat

MkDocs adalah generator situs statis sumber terbuka yang dirancang untuk membuat dokumentasi proyek dan API. Anda menulis konten dalam Markdown—format berbasis teks yang ringan—dan MkDocs mengubahnya menjadi situs HTML statis modern dengan navigasi, pencarian, dan tema yang dapat disesuaikan, tanpa memerlukan database atau skrip sisi server. Ini sempurna untuk dokumentasi API karena sederhana, mendukung Markdown untuk pembuatan konten yang mudah, dan menghasilkan file statis yang dapat Anda host di mana saja, seperti GitHub Pages atau Read the Docs. Para pengembang memuji kecepatannya dan kemudahannya, dan komunitas MkDocs GitHub ramai dengan plugin dan tema untuk mempercantiknya. Apakah Anda mendokumentasikan REST API atau paket Python, MkDocs menjaganya tetap bersih dan ramah pengguna. Mari kita siapkan!

Menyiapkan Lingkungan Anda untuk MkDocs

Sebelum kita mulai membangun dengan MkDocs, mari siapkan sistem Anda. Ini sangat ramah pemula, dan saya akan menjelaskan setiap langkah agar Anda tidak tersesat.

Periksa Prasyarat: Anda memerlukan beberapa alat yang terinstal:

  • Python: Versi 3.7 atau lebih tinggi (MkDocs tidak lagi mendukung Python 2). Jalankan python --version di terminal Anda. Jika tidak ada atau sudah usang, unduh dari python.org. Di Windows, pastikan Python ditambahkan ke PATH Anda selama instalasi—centang kotak di penginstal.
  • pip: Manajer paket Python, biasanya disertakan dengan Python 3.4+. Verifikasi dengan pip --version. Jika tidak ada, unduh get-pip.py dari web dan jalankan python get-pip.py.
  • Git: Opsional untuk penyebaran ke GitHub Pages. Periksa dengan git --version. Instal dari git-scm.com jika diperlukan.

Ada yang kurang? Instal sekarang untuk menghindari masalah.

Buat Folder Proyek: Mari kita jaga semuanya tetap rapi dengan membuat folder khusus untuk proyek MkDocs Anda:

mkdir mkdocs-api-docs
cd mkdocs-api-docs

Folder ini akan menampung file MkDocs Anda, dan cd akan membawa Anda masuk ke dalamnya, siap beraksi.

Siapkan Lingkungan Virtual: Untuk menghindari konflik paket, buat lingkungan virtual Python:

python -m venv venv

Aktifkan:

  • Mac/Linux: source venv/bin/activate
  • Windows: venv\Scripts\activate

Anda akan melihat (venv) di terminal Anda, yang berarti Anda berada di lingkungan Python yang bersih. Ini mengisolasi dependensi MkDocs, menjaga sistem Anda tetap rapi.

aktifkan lingkungan virtual

Menginstal MkDocs

Sekarang, mari kita instal MkDocs dan siapkan untuk membangun dokumentasi API Anda. Ini cepat dan mudah.

Instal MkDocs: Dengan lingkungan virtual aktif, jalankan:

pip install mkdocs

Ini mengambil MkDocs dari PyPI dan menginstalnya. Mungkin perlu waktu sejenak untuk mengunduh dependensi seperti Markdown dan Pygments.

Verifikasi Instalasi: Periksa apakah MkDocs terinstal dengan benar:

mkdocs --version

Anda akan melihat sesuatu seperti mkdocs, version 1.6.1 (atau yang lebih baru). Jika gagal, pastikan pip diperbarui (pip install --upgrade pip) atau Python ada di PATH Anda.

Instal Tema (Opsional): MkDocs dilengkapi dengan tema dasar (readthedocs & mkdocs), tetapi tema Material for MkDocs adalah favorit penggemar karena tampilannya yang modern. Instal:

pip install mkdocs-material

Ini menambahkan tema yang rapi dan dapat disesuaikan yang sempurna untuk dokumen API. Kita akan menggunakannya nanti untuk membuat situs Anda menonjol.

tema dan versi mkdocs

Membuat dan Menggunakan Proyek MkDocs Anda

Saatnya membuat proyek MkDocs Anda dan membangun beberapa dokumentasi API! Kita akan menyiapkan situs sederhana untuk mendokumentasikan REST API fiksi, dengan halaman beranda dan halaman endpoint.

Inisialisasi Proyek Baru: Di folder mkdocs-api-docs Anda (dengan lingkungan virtual aktif), buat proyek MkDocs baru:

mkdocs new .

Ini membuat:

  • mkdocs.yml: File konfigurasi untuk situs Anda.
  • docs/: Folder dengan file index.md, halaman beranda default.

Folder docs/ adalah tempat file Markdown Anda berada, dan index.md adalah titik masuk situs Anda.

Edit File Konfigurasi: Buka mkdocs.yml di editor teks (misalnya, VS Code dengan code .). Perbarui untuk mengatur nama situs, tema, dan navigasi untuk dokumen API Anda:

site_name: My API Documentation
theme:
  name: material
nav:
  - Home: index.md
  - Endpoints: endpoints.md

Ini mengatur nama situs, menerapkan tema Material (jika terinstal), dan mendefinisikan menu navigasi dengan dua halaman: "Home" (index.md) dan "Endpoints" (endpoints.md). Simpan file.

Tulis Dokumentasi API Anda: Mari kita buat konten untuk dokumen API Anda:

Edit docs/index.md: Ganti isinya dengan:

# Selamat Datang di Dokumentasi API Saya

Ini adalah dokumentasi untuk REST API kami yang luar biasa. Gunakan navigasi untuk menjelajahi endpoint dan memulai!

Buat docs/endpoints.md: Tambahkan file baru di folder docs/ bernama endpoints.md dengan:

# Endpoint API

## GET /users

Mengambil daftar pengguna.

**Contoh Permintaan**:
```bash
curl -X GET https://api.example.com/users

Respon:

[
  {"id": 1, "name": "Alice"},
  {"id": 2, "name": "Bob"}
]

File Markdown ini mendefinisikan halaman beranda API Anda dan contoh endpoint, menggunakan blok kode untuk kejelasan. Jangan ragu untuk menambahkan lebih banyak endpoint atau detail!

Pratinjau Situs Anda: Mulai server pengembangan MkDocs untuk melihat dokumen Anda secara langsung:

mkdocs serve

Ini membangun situs Anda dan menghostingnya di http://127.0.0.1:8000/. Buka URL tersebut di browser Anda, dan Anda akan melihat dokumen API Anda dengan bilah navigasi, pencarian, dan desain ramping tema Material (jika terinstal). Server otomatis memuat ulang saat Anda mengedit file mkdocs.yml atau Markdown, jadi sesuaikan dan lihat perubahan secara langsung!

mkdocs serve

Saya menguji pengaturan ini, dan dokumen API saya terlihat profesional dalam waktu kurang dari 10 menit—navigasi berfungsi, dan pencarian menemukan detail endpoint saya secara instan. Jika server tidak mau mulai, periksa apakah port 8000. bebas atau mkdocs terinstal dengan benar.

halaman depan mkdocs

Menyebarkan Situs MkDocs Anda

Dokumen API Anda terlihat tajam secara lokal—sekarang mari kita bagikan ke dunia dengan menyebarkannya ke GitHub Pages, opsi hosting gratis.

Buat Repositori Git: Inisialisasi repositori Git di folder mkdocs-api-docs Anda:

git init
git add .
git commit -m "Initial MkDocs project"

Ini menyiapkan kontrol versi. Tambahkan site/ dan venv/ ke file .gitignore untuk mengecualikan artefak build dan lingkungan virtual:

site/
venv/

Push ke GitHub: Buat repositori baru di GitHub (misalnya, my-api-docs) dan push proyek Anda:

git remote add origin https://github.com/yourusername/my-api-docs.git
git branch -M main
git push -u origin main

Ganti yourusername dengan nama pengguna GitHub Anda. Ini mengunggah proyek MkDocs Anda ke GitHub.

Sebarkan ke GitHub Pages: Bangun dan sebarkan situs Anda:

mkdocs gh-deploy

Perintah ini membangun situs Anda, melakukan commit file statis ke cabang gh-pages, dan mendorongnya ke GitHub. MkDocs menggunakan alat ghp-import di balik layar untuk menangani ini. Situs Anda akan aktif di https://yourusername.github.io/my-api-docs/ (berikan beberapa menit untuk menyebar).

Saya menjalankan ini untuk situs uji saya, dan situs itu aktif di GitHub Pages dalam waktu kurang dari satu menit, dapat diakses oleh siapa pun dengan tautannya. Jika tidak berfungsi, pastikan repositori GitHub Anda bersifat publik dan periksa mkdocs gh-deploy --help untuk opsi.

Menjelajahi Alternatif MkDocs: Dokumentasi APIdog

Meskipun MkDocs fantastis untuk dokumentasi API yang ringan, Anda mungkin menginginkan alat dengan lebih banyak fitur tambahan. Hadirlah Dokumentasi APIdog, alternatif canggih yang terlihat lebih bagus, kaya fitur, dan mendukung self-hosting. APIdog mengintegrasikan desain API, pengujian, dan dokumentasi dalam satu platform, menawarkan playground API interaktif, pengujian otomatis, dan fitur kolaboratif—sempurna untuk tim yang membutuhkan lebih dari sekadar dokumen statis. Ini sedikit lebih kompleks daripada MkDocs, tetapi jika Anda menginginkan solusi lengkap yang rapi, cobalah APIdog!

dokumentasi apidog

Jika Anda baru memulai menulis dokumentasi atau ingin meningkatkan keterampilan dokumentasi Anda—terutama saat bekerja dalam tim atau menangani proyek yang kompleks—saya sangat merekomendasikan Anda mencoba Apidog. Ini menawarkan banyak fitur yang menyederhanakan pengelolaan dokumentasi untuk proyek yang kompleks atau kolaboratif. Dan bagian terbaiknya adalah, Anda bisa memulai secara gratis!

button

Tips untuk Sukses dengan MkDocs

  • Sesuaikan Tema Anda: Sesuaikan tema Material di mkdocs.yml dengan opsi seperti palette: { scheme: slate } untuk tampilan mode gelap.
  • Tambahkan Plugin: Instal plugin seperti mkdocs-mkdocstrings untuk integrasi docstring Python atau mkdocs-pdf-export-plugin untuk ekspor PDF.
  • Gunakan Ekstensi Markdown: Aktifkan ekstensi di mkdocs.yml (misalnya, markdown_extensions: - toc: permalink: true) untuk daftar isi atau catatan khusus.
  • Periksa Log: Jika mkdocs serve atau gh-deploy gagal, periksa output terminal atau mkdocs --help untuk petunjuk.
  • Jelajahi Komunitas: Bergabunglah dengan Diskusi GitHub MkDocs atau obrolan Gitter untuk tips dan ide plugin.

Penutup: Petualangan MkDocs Anda Dimulai

Selamat—Anda telah menginstal, menggunakan, dan menyebarkan MkDocs untuk membuat dokumentasi API yang rapi! Dari menyiapkan proyek hingga menyebarkan di GitHub Pages, Anda telah membangun situs profesional yang mudah dipelihara dan dibagikan. Coba tambahkan lebih banyak endpoint, bereksperimen dengan plugin, atau sesuaikan tema untuk membuatnya menjadi milik Anda. Jika Anda menginginkan alternatif yang kaya fitur, lihat Dokumentasi APIdog untuk pengalaman tingkat berikutnya! Selamat mendokumentasikan!