Berfungsi dengan halaman Material for MkDocs
Indeks panduan, halaman referensi, dan HTML statis yang dihasilkan dari situs MkDocs atau Material for MkDocs publik tanpa mengganti tema Anda.
Chatbot AI untuk dokumentasi MkDocs dan Material for MkDocs. ChattyBox merayapi situs publik Anda dan dapat menyertakan tautan ke halaman yang diambil dalam jawaban. Uji keakuratan jawaban dan kutipan. Tidak ada pipeline pengindeksan Python atau RAG khusus yang perlu dipelihara.
ChattyBox merayapi situs web, dokumentasi, pusat bantuan, CMS, atau basis pengetahuan yang sudah ada. Konten yang diambil dapat memandu jawaban chatbot; periksa keakuratan jawaban dan sitasinya.
Lakukan crawling pada sitemap MkDocs yang telah di-deploy atau jalur stabil dan berversi yang sengaja Anda dukung.
Uji pertanyaan produk, Python, dan API serta buka setiap kutipan sebelum instalasi.
Untuk Material, konfigurasikan theme.custom_dir dan perluas base.html dari overrides/main.html sambil mempertahankan blok scripts dengan super().
Verifikasi pencarian bawaan, navigasi instan, kontrol seluler, CSP, dan setiap versi mike yang dipublikasikan.
Peluncuran tiga langkah
Tim MkDocs biasanya menginginkan pembuatan statis yang cepat, navigasi yang jelas, dan konten teknis yang dapat dibaca. ChattyBox menjaga alur kerja tetap utuh sambil menambahkan asisten yang dikutip sumber di atas situs yang dipublikasikan.
Gunakan pos pemeriksaan ini untuk memutuskan apakah ChattyBox harus ditempatkan di samping platform dokumen Anda, menggantikan asisten terpisah, atau tetap terisolasi untuk pengujian.
Indeks panduan, halaman referensi, dan HTML statis yang dihasilkan dari situs MkDocs atau Material for MkDocs publik tanpa mengganti tema Anda.
Arahkan ChattyBox ke jalur versi yang ingin ditanyakan oleh pengguna, lalu uji apakah jawaban mengutip dokumentasi stabil, terbaru, atau lama yang dimaksud.
Karena ChattyBox merayapi situs publik, tim tidak perlu menambahkan pengindeksan vektor ke alur build MkDocs atau skrip CI mereka.
Pada Pro atau Business, tinjau pertanyaan yang ditandai sebagai sinyal heuristik tentang kemungkinan contoh yang hilang, langkah instalasi yang tidak jelas, atau halaman pemecahan masalah yang sudah usang.
Material for MkDocs dan tema bawaan MkDocs sama-sama mendukung pewarisan template, tetapi harus menggunakan direktori khusus yang terpisah. Jalur Material di bawah mempertahankan blok scripts dengan super(), menambahkan satu loader async, dan tetap berfungsi dalam navigasi instan tanpa mengganti perilaku pencarian.
Periksa kembali blok template dan perilaku navigasi instan setelah upgrade tema, serta lakukan crawling ulang setiap kali alias mike berpindah.
| Aspek MkDocs | Keputusan implementasi | Verifikasi |
|---|---|---|
Aspek MkDocs Override Material | Keputusan implementasi Atur theme.name ke material dan theme.custom_dir ke overrides. Perluas base.html, override scripts, panggil super(), lalu tambahkan skrip widget. | Verifikasi Build dan sajikan situs, lalu pastikan pencarian dan navigasi Material tetap berfungsi. |
Aspek MkDocs MkDocs vanilla | Keputusan implementasi Gunakan theme.name: mkdocs dengan direktori custom_theme terpisah. Tambahkan override custom_theme/main.html yang setara alih-alih menyalin template Material. | Verifikasi Jalankan mkdocs serve dan verifikasi pencarian, tautan berikutnya dan sebelumnya, serta widget pada lebih dari satu halaman. |
Aspek MkDocs Pemuatan async dan duplikat | Keputusan implementasi Pertahankan satu loader dalam blok scripts yang diwariskan, beri ID stabil, dan jangan tambahkan snippet yang sama melalui extra_javascript atau partial lain. | Verifikasi Setelah pemuatan penuh dan transisi instan Material, pastikan document.querySelectorAll("#chattybox-widget").length bernilai 1. |
Aspek MkDocs Kebijakan Keamanan Konten | Keputusan implementasi Izinkan chattybox.ai di script-src, origin API yang dikonfigurasi di connect-src, fonts.googleapis.com di style-src, dan fonts.gstatic.com di font-src. Widget saat ini menyisipkan CSS komponennya sendiri, sehingga style-src yang ketat juga memerlukan 'unsafe-inline' sampai build berbasis nonce atau stylesheet eksternal tersedia. | Verifikasi Periksa konsol browser dan panel Network untuk permintaan script, style, font, fetch, atau WebSocket yang diblokir. |
Aspek MkDocs Pencarian, navigasi instan, dan perangkat seluler | Keputusan implementasi Pertahankan skrip tema dengan super() dan jaga launcher agar tidak menghalangi dialog pencarian, drawer, paginasi, dan kontrol persetujuan. | Verifikasi Uji pencarian keyboard, beberapa tautan instan, dan viewport 390 piksel tanpa tumpang tindih atau pengguliran horizontal. |
Aspek MkDocs Versi mike | Keputusan implementasi Pilih jalur versi stable, latest, atau eksplisit secara sengaja. Lakukan crawling ulang setelah memindahkan alias, dan kecualikan rilis yang tidak didukung jika jawaban lintas versi dapat menyesatkan pengguna. | Verifikasi Gunakan mike serve untuk menguji pergantian versi dan memastikan kutipan dapat diakses dalam versi yang dimaksud. |
Aspek MkDocs Kegagalan widget atau kutipan | Keputusan implementasi Periksa indentasi YAML, custom_dir aktif, nama blok yang diwariskan, kunci API, CSP, isi sitemap, dan apakah build yang di-deploy menyertakan override. | Verifikasi Periksa HTML yang dihasilkan dan uji artefak produksi alih-alih hanya mengandalkan live reload. |
Gunakan pertanyaan tema dengan aturan template yang dapat diverifikasi, lalu buka kutipan dan pastikan cocok dengan versi yang dipilih pengunjung Anda.
Daftar periksa praktis untuk mengevaluasi chatbot AI dokumentasiUntuk Material for MkDocs, atur theme.custom_dir ke overrides, perluas base.html di overrides/main.html, dan panggil super() sebelum skrip widget async. MkDocs vanilla memerlukan direktori tema khusus tersendiri dan override main.html yang setara.
{% 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="https://adorable-woodpecker-629.convex.site/chat"
data-chattybox-widget="true"
></script>
{% endblock %}Ya. ChattyBox dapat merayapi halaman publik MkDocs dan Material for MkDocs serta disematkan sebagai widget situs web standar.
Tidak. Tambahkan cuplikan widget ke templat situs Anda atau penggantian tema setelah mengonfigurasi chatbot.
Ya, jika laman dokumen berversi bersifat publik dan disertakan dalam perayapan atau peta situs.
Pada Pro atau Business, pertanyaan yang ditandai merupakan sinyal heuristik untuk menyelidiki kemungkinan kesenjangan, bukan diagnosis pasti atas konten MkDocs Anda.