Chatbot AI dengan sumber untuk Docusaurus 3

Setelah pemuatan halaman pertama, Docusaurus berperilaku seperti aplikasi satu halaman. Integrasi widget yang hanya berfungsi pada dokumen awal, atau yang menambahkan loader kedua pada setiap perubahan rute, belum siap untuk produksi. Panduan ini menggunakan identitas skrip yang stabil dan root tema yang tetap terpasang di seluruh rute dokumentasi.

Penulis dan peninjau teknis: Michael Fisher, pemelihara ChattyBox. Dipublikasikan dan diperiksa secara teknis pada 10 Juli 2026. Pemeriksaan yang dapat diulang di bawah ini adalah tutorial implementasi, bukan benchmark performa atau akurasi.

1. Tambahkan komponen tema Root

Buat src/theme/Root.tsx di situs Docusaurus Anda:

import React, { useEffect, type ReactNode } from 'react';

const WIDGET_ID = 'chattybox-widget';

export default function Root({ children }: { children: ReactNode }) {
  useEffect(() => {
    if (document.getElementById(WIDGET_ID)) return;

    const script = document.createElement('script');
    script.id = WIDGET_ID;
    script.src = 'https://chattybox.ai/widget.js';
    script.async = true;
    script.dataset.apiKey = 'YOUR_API_KEY';
    script.dataset.apiUrl = 'YOUR_CHAT_API_URL';
    script.dataset.chattyboxWidget = 'true';
    document.body.appendChild(script);
  }, []);

  return <>{children}</>;
}

ID chattybox-widget yang stabil adalah bagian terpenting. React Strict Mode dapat melakukan remount pada effect selama pengembangan, dan Docusaurus mengubah rute tanpa mengganti dokumen. Guard tersebut membuat kedua kasus ini idempoten.

Gunakan URL API yang ditampilkan oleh proyek ChattyBox Anda, bukan menyalin deployment contoh. Lihat referensi instalasi widget untuk atribut terbaru dan panduan produk Docusaurus untuk panduan pemilihan sumber dan evaluasi.

2. Pertahankan loader tetap terpasang

Jangan menempatkan skrip ini di dalam halaman dokumentasi individual atau layout yang diganti Docusaurus selama navigasi. Komponen Root yang telah di-swizzle membungkus aplikasi selama masa hidupnya, sehingga widget tetap tersedia saat pengunjung berpindah di antara panduan dan referensi.

Jika situs Anda sudah memiliki src/theme/Root.tsx, gabungkan effect ke komponen yang ada, bukan mengganti provider autentikasi, analytics, atau provider lainnya.

3. Perhitungkan Content Security Policy

Kebijakan yang ketat perlu mengizinkan:

• https://chattybox.ai dalam script-src untuk loader widget.
• Origin API chat yang Anda konfigurasi dalam connect-src.
• https://fonts.googleapis.com dalam style-src dan https://fonts.gstatic.com dalam font-src jika font widget belum tersedia.
• Gaya komponen inline dalam style-src untuk build widget saat ini.

Mulailah dari kebijakan yang sudah ada dan tambahkan hanya origin yang benar-benar Anda gunakan. Jangan mengganti kebijakan yang ketat dengan wildcard yang luas.

4. Ulangi pemeriksaan integrasi

Di proyek Docusaurus Anda, tambahkan wrapper Root di atas lalu jalankan:

bun install
bun run start

Kemudian verifikasi:

1. Buka dua rute dokumentasi yang berbeda tanpa melakukan refresh penuh pada browser.
2. Jalankan document.querySelectorAll('#chattybox-widget').length setelah setiap navigasi. Nilainya harus tetap 1.
3. Ajukan pertanyaan yang dijawab oleh halaman terindeks dan pastikan responsnya menautkan ke halaman tersebut.
4. Ajukan pertanyaan yang tidak didukung dan pastikan asisten menggunakan fallback, bukan mengarang sumber.
5. Uji launcher pada viewport seluler yang sempit dan pastikan launcher tidak menutupi kontrol navigasi atau pagination.

Pemeriksaan jumlah skrip membuktikan pencegahan duplikasi. Pemeriksaan ini tidak membuktikan kualitas retrieval. Gunakan kumpulan pertanyaan yang representatif dan panduan scraping untuk memvalidasi cakupan sumber sebelum peluncuran.

Hal yang perlu dipantau setelah peluncuran

Catat pertanyaan yang belum terselesaikan, kutipan yang keliru, halaman sumber yang sudah usang, dan rute tempat launcher menutupi kontrol situs. Uji ulang setelah upgrade tema Docusaurus karena perubahan pada navigasi dan tata letak konten dapat memengaruhi penempatan meskipun loader tetap benar.

Untuk urutan peluncuran yang lebih menyeluruh, gunakan checklist implementasi chatbot dokumentasi dan checklist peluncuran.

Sumber

• Referensi instalasi widget ChattyBox
• Dokumentasi swizzling Docusaurus
• Panduan Content Security Policy MDN