Panduan Implementasi Halaman Dokumentasi

Pengenalan Messara #

Messara adalah platform manajemen operasional dan analitik modern yang dibangun di atas teknologi stack terbaik: Laravel 11 di sisi backend, Inertia.js (React 19) di antarmuka frontend, dan utilitas visual Tailwind CSS v4.

Dokumentasi ini dirancang dengan standar desain kelas enterprise: navigasi hirarkis responsif di segala layar, modal pencarian instan (Command Palette), blok kode dengan tombol salin interaktif, callout multi-warna, dan scrollspy table of contents.

1. Prinsip Desain & Fitur Kunci #

Desain ini mengadopsi seluruh filosofi antarmuka modern laravel.com/docs:

2. Arsitektur & Struktur File #

Struktur penempatan modul dokumentasi di dalam proyek messara_baru/ disarankan sebagai berikut:

messara_baru/
├── app/
│   └── Http/
│       └── Controllers/
│           └── DocumentationController.php       # Controller perutean dokumentasi
├── resources/
│   └── js/
│       ├── layouts/
│       │   └── docs-layout.tsx                   # Layout khusus docs (Header, Sidebar, TOC)
│       ├── components/
│       │   └── docs/
│       │       ├── docs-sidebar.tsx              # Sidebar navigasi kiri
│       │       ├── docs-toc.tsx                  # "On this page" TOC kanan
│       │       ├── docs-callout.tsx              # Komponen alert (Note, Tip, Warning)
│       │       ├── docs-code-block.tsx           # Block kode + Copy button
│       │       ├── docs-step.tsx                 # Timeline langkah visual
│       │       └── docs-search-dialog.tsx        # Modal pencarian cepat (cmdk)
│       └── pages/
│           └── docs/
│               ├── index.tsx                     # Halaman pembuka / Overview
│               └── show.tsx                      # Render dinamis konten dokumen

Prasyarat Sistem #

Sebelum menginstal dan menjalankan proyek Messara, pastikan komputer Anda memenuhi spesifikasi minimum berikut:

• PHP: versi 8.2 atau lebih tinggi
• Composer: versi 2.x
• Node.js: versi 20.x atau 22.x LTS (disertai npm)
• Database: PostgreSQL 15+ atau MySQL 8+

Langkah Instalasi #

Ikuti 4 langkah terpandu di bawah ini untuk mempersiapkan proyek dari awal:

git clone https://github.com/AksaraTeknologi/messara.git
cd messara

cp .env.example .env

composer install
npm install

php artisan key:generate
php artisan migrate --seed

Menjalankan Aplikasi #

Untuk memulai local development server, jalankan perintah concurrently berikut di terminal:

# Terminal 1 - Backend Laravel
php artisan serve

# Terminal 2 - Frontend Vite HMR
npm run dev

Langkah 1: Routing & Controller #

Konfigurasi endpoint perutean di Laravel menggunakan file routes/web.php dan DocumentationController.php:

use App\Http\Controllers\DocumentationController;

Route::prefix('docs')->name('docs.')->group(function () {
    Route::get('/', [DocumentationController::class, 'index'])->name('index');
    Route::get('/{section}/{page?}', [DocumentationController::class, 'show'])->name('show');
});

namespace App\Http\Controllers;

use Illuminate\Http\Request;
use Inertia\Inertia;

class DocumentationController extends Controller
{
    public function index()
    {
        return Inertia::render('docs/index');
    }

    public function show(string $section, ?string $page = null)
    {
        return Inertia::render('docs/show', [
            'section' => $section,
            'page' => $page ?? 'overview',
        ]);
    }
}

Langkah 2: Definisi Data Navigasi #

Konfigurasi array navigasi tersentralisasi di resources/js/config/docs-navigation.ts:

export interface NavItem {
    title: string;
    href: string;
    badge?: string;
}

export interface NavSection {
    title: string;
    items: NavItem[];
}

export const docsNavigation: NavSection[] = [
    {
        title: "Memulai (Getting Started)",
        items: [
            { title: "Pendahuluan", href: "/docs/getting-started/introduction" },
            { title: "Instalasi & Setup", href: "/docs/getting-started/installation" },
            { title: "Struktur Proyek", href: "/docs/getting-started/structure" },
            { title: "Konfigurasi Lingkungan", href: "/docs/getting-started/configuration" },
        ],
    },
    {
        title: "Arsitektur & Konsep Inti",
        items: [
            { title: "Alur Autentikasi", href: "/docs/core/authentication" },
            { title: "Peran & Izin (RBAC)", href: "/docs/core/roles-permissions" },
            { title: "Database & Skema", href: "/docs/core/database-schema" },
            { title: "Manajemen State & Inertia", href: "/docs/core/inertia-state" },
        ],
    },
];

Komponen Callout / Alerts #

Berikut adalah 4 ragam variasi callout alert yang dapat langsung digunakan:

Komponen Code Block Interaktif #

Komponen DocsCodeBlock menyediakan tampilan profesional dengan tombol salin instan satu-klik:

import React, { useState } from 'react';
import { Check, Copy, Terminal } from 'lucide-react';

interface DocsCodeBlockProps {
    code: string;
    language?: string;
    filename?: string;
}

export function DocsCodeBlock({ code, language = 'bash', filename }: DocsCodeBlockProps) {
    const [copied, setCopied] = useState(false);

    const handleCopy = () => {
        navigator.clipboard.writeText(code);
        setCopied(true);
        setTimeout(() => setCopied(false), 2000);
    };

    return (
        <div className="my-6 overflow-hidden rounded-xl border border-zinc-800 bg-zinc-950 font-mono text-xs sm:text-sm shadow-xl">
            {/* Header & Body */}
        </div>
    );
}

Komponen Step Timeline Visual #

Komponen DocsStepTimeline memudahkan pemaparan urutan prosedur bertahap yang mudah diikuti pembaca pada desktop maupun smartphone.

Layout Sidebar & Header Dokumentasi #

Layout menyatukan Header fixed, Sidebar kiri ber-scroll mandiri (atau drawer geser pada mobile), dan Table of Contents di sebelah kanan.

Panduan Menambah Bab & Konten Baru #

Untuk menambahkan halaman dokumentasi baru pada proyek Messara:

1. Tambahkan Navigasi: Buka file resources/js/config/docs-navigation.ts dan tambahkan item baru pada array docsNavigation.
2. Buat View Halaman: Tambahkan file halaman baru pada direktori resources/js/pages/docs/[kategori]/[judul].tsx.
3. Definisikan tocItems: Sediakan array { id, title, level } yang sesuai dengan atribut id pada tag <section> atau <h2 id="...">.
4. Gunakan Elemen Interaktif: Manfaatkan <DocsCallout>, <DocsCodeBlock>, dan <DocsStepTimeline>.

Ringkasan Fitur & Kemampuan #

Dengan template ini, dokumentasi aplikasi Messara siap dipublikasikan untuk tim internal maupun publik dengan standar Laravel Docs.