Tambahkan chatbot AI dengan sumber ke MkDocs
Tema MkDocs menyediakan direktori override yang berbeda, dan Material dapat berpindah antarhalaman tanpa pemuatan ulang penuh. Integrasi yang tahan lama harus mempertahankan skrip bawaan tema, memuat widget satu kali, serta berjalan bersama pencarian dan navigasi pada perangkat seluler.
Penulis dan peninjau teknis: Michael Fisher, pemelihara ChattyBox. Dipublikasikan dan diperiksa secara teknis pada 10 Juli 2026. Protokol verifikasi di bawah ini adalah tutorial implementasi; tidak ada klaim hasil terkait trafik, pengalihan, atau akurasi jawaban.
1. Pilih direktori override yang tepat
Untuk Material for MkDocs, arahkan custom_dir ke direktori overrides:
site_name: My documentation
theme:
name: material
custom_dir: overrides
features:
- navigation.instant
Untuk tema bawaan, gunakan direktori tema kustom yang terpisah:
site_name: My documentation
theme:
name: mkdocs
custom_dir: custom_theme
Memisahkan kedua varian memperjelas template dasar upstream mana yang diperluas.
2. Perluas blok scripts
Buat overrides/main.html untuk Material atau custom_theme/main.html untuk tema bawaan:
{% extends "base.html" %}
{% block scripts %}
{{ super() }}
<script
id="chattybox-widget"
src="https://chattybox.ai/widget.js"
async
data-api-key="YOUR_API_KEY"
data-api-url="YOUR_CHAT_API_URL"
data-chattybox-widget="true"
></script>
{% endblock %}
{{ super() }} mempertahankan skrip yang disediakan tema, termasuk perilaku navigasi dan pencarian. Menghilangkannya dapat membuat widget terlihat berfungsi, tetapi diam-diam merusak antarmuka dokumentasi. ID yang stabil juga memberi Anda assertion langsung untuk loader duplikat.
Gunakan nilai khusus proyek dari referensi instalasi widget. Panduan chatbot AI MkDocs membahas cakupan sumber, perilaku crawl, dan pertanyaan yang perlu dievaluasi sebelum dipublikasikan.
3. Bangun kedua varian
Dari proyek MkDocs Anda:
python -m venv .venv
. .venv/bin/activate
pip install -r requirements.txt
cd material
mkdocs build --strict
cd ../vanilla
mkdocs build --strict
--strict mengubah peringatan menjadi kegagalan sehingga masalah navigasi dan konfigurasi yang rusak terdeteksi sebelum widget dievaluasi.
4. Jalankan pemeriksaan browser
Sajikan setiap varian lalu verifikasi:
- Pencarian bawaan masih terbuka dan mengembalikan hasil dokumentasi yang diharapkan.
- Material instant navigation mengubah rute tanpa menggandakan loader widget.
document.querySelectorAll('#chattybox-widget').lengthtetap1setelah beberapa perubahan rute.- Pada viewport 390 px, launcher tidak menutupi pencarian, navigasi, atau kontrol berikutnya/sebelumnya.
- Pertanyaan yang didukung mengutip halaman yang diharapkan, dan pertanyaan yang tidak didukung menghasilkan fallback yang konservatif.
Empat pemeriksaan pertama memvalidasi perilaku integrasi. Pemeriksaan kelima bergantung pada halaman yang Anda indeks dan memerlukan set evaluasi yang representatif; ikuti panduan scraping dan checklist peluncuran alih-alih menganggap skrip yang berhasil dimuat sebagai bukti kualitas jawaban.
5. Pertahankan CSP yang ketat
Izinkan host widget dalam script-src, origin API yang dikonfigurasi dalam connect-src, serta origin font dalam style-src dan font-src jika diperlukan. Widget saat ini menyuntikkan gaya komponen, sehingga kebijakan yang selain itu sudah ketat juga memerlukan strategi gaya inline yang eksplisit. Hindari daftar source wildcard.
Checklist pemeliharaan
Bangun ulang kedua varian tema setelah upgrade MkDocs atau Material karena nama blok template upstream dapat berubah. Pertahankan ID skrip, pertahankan super(), lalu jalankan kembali pemeriksaan pencarian, instant navigation, tumpang tindih seluler, dan kutipan sumber.
Untuk merencanakan peluncuran menyeluruh, gunakan checklist implementasi chatbot dokumentasi.