Lewati ke konten utama
ChattyBoxMulai Free

Tambahkan chatbot AI dengan sumber ke MkDocs

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

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 membantu menghitung skrip ini; ID tersebut tidak mendeteksi loader lain dengan ID berbeda atau tanpa ID.

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​

Unduh dan ekstrak contoh MkDocs, lalu jalankan perintah ini dari direktori examples/mkdocs-chattybox yang telah diekstrak. Direktori tersebut berisi requirements.txt serta proyek material dan vanilla yang terpisah. Untuk proyek yang sudah ada, gunakan dependensi dan direktori proyeknya sendiri.

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:

  1. Pencarian bawaan masih terbuka dan mengembalikan hasil dokumentasi yang diharapkan.
  2. Material instant navigation mengubah rute tanpa menggandakan loader widget.
  3. document.querySelectorAll('#chattybox-widget').length tetap 1 setelah beberapa perubahan rute.
  4. Pada viewport 390 px, launcher tidak menutupi pencarian, navigasi, atau kontrol berikutnya/sebelumnya.
  5. Pertanyaan yang didukung mengutip halaman yang diharapkan; uji perilaku fallback yang konservatif untuk pertanyaan yang tidak didukung tanpa menganggap setiap respons akan menahan diri untuk menjawab.

Penghitungan ID hanya mencakup skrip tersebut; periksa juga integrasi lain dan widget yang dirender untuk menemukan duplikasi. 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, dan origin gambar ikon kustom apa pun dalam img-src. Untuk widget v16 pada kode sumber saat ini, izinkan origin Google Fonts dalam style-src dan font-src ketika stylesheet Inter disuntikkan; periksa perilaku loader yang di-deploy. 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.

Sumber​