Lewati ke konten utama
ChattyBoxMulai Free

Chatbot AI dengan sumber untuk Docusaurus 3

· 4 mnt baca
Michael Fisher
Michael Fisher
ChattyBox maintainer and technical writer

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 menjaga penyisipan khusus ini saat React melakukan remount selama pengembangan dan saat rute berubah di sisi klien. Guard ini tidak mendeteksi loader terpisah dengan ID berbeda atau tanpa ID; gunakan hanya satu integrasi per halaman.

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.
  • Untuk loader pada kode sumber saat ini, https://fonts.googleapis.com dalam style-src dan https://fonts.gstatic.com dalam font-src ketika loader menyuntikkan stylesheet Inter. Tautan stylesheet Google Fonts yang cocok mencegah penyisipan tersebut; ketersediaan font saja tidak. Periksa perilaku loader yang di-deploy.
  • Origin gambar ikon kustom apa pun yang dikonfigurasi dalam img-src.
  • 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 evaluasi apakah asisten menggunakan fallback alih-alih mengarang sumber; ulangi dengan kasus yang representatif tanpa menganggap setiap respons akan menahan diri untuk menjawab.
  5. Uji launcher pada viewport seluler yang sempit dan pastikan launcher tidak menutupi kontrol navigasi atau pagination.

Pemeriksaan jumlah skrip hanya menghitung ID tersebut; loader terpisah tanpa ID atau dengan ID berbeda masih mungkin ada. Periksa juga semua integrasi dan widget yang dirender. Jumlah tersebut 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​