Dodaj chatbota AI z cytowaniami do MkDocs
Motywy MkDocs udostępniają różne katalogi nadpisywania, a Material może przechodzić między stronami bez pełnego przeładowania. Trwała integracja musi zachować istniejące skrypty motywu, załadować widget tylko raz oraz współdziałać z wyszukiwaniem i nawigacją na urządzeniach mobilnych.
Autor i recenzent techniczny: Michael Fisher, opiekun ChattyBox. Opublikowano i sprawdzono technicznie 10 lipca 2026 r. Poniższy protokół weryfikacji jest samouczkiem implementacyjnym; nie deklaruje się żadnego wyniku dotyczącego ruchu, odciążenia wsparcia ani dokładności odpowiedzi.
1. Wybierz właściwy katalog nadpisywania
W przypadku Material for MkDocs wskaż custom_dir na katalog overrides:
site_name: My documentation
theme:
name: material
custom_dir: overrides
features:
- navigation.instant
W przypadku wbudowanego motywu użyj osobnego katalogu niestandardowego motywu:
site_name: My documentation
theme:
name: mkdocs
custom_dir: custom_theme
Rozdzielenie wariantów jasno wskazuje, który nadrzędny szablon bazowy jest rozszerzany.
2. Rozszerz blok scripts
Utwórz overrides/main.html dla Material albo custom_theme/main.html dla wbudowanego motywu:
{% 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() }} zachowuje skrypty dostarczane przez motyw, w tym działanie nawigacji i wyszukiwania. Pominięcie go może sprawić, że widget będzie wyglądać na działający, jednocześnie po cichu psując interfejs dokumentacji. Stabilny identyfikator pozwala także bezpośrednio sprawdzić, czy loader nie został zduplikowany.
Użyj wartości właściwych dla projektu z dokumentacji instalacji widgetu. Przewodnik po chatbocie AI dla MkDocs omawia zakres źródeł, działanie crawlowania oraz pytania, które należy ocenić przed publikacją.
3. Zbuduj oba warianty
W projekcie MkDocs uruchom:
python -m venv .venv
. .venv/bin/activate
pip install -r requirements.txt
cd material
mkdocs build --strict
cd ../vanilla
mkdocs build --strict
--strict zamienia ostrzeżenia w błędy, dzięki czemu wykrywa problemy z nawigacją i konfiguracją, zanim widget zostanie poddany ewaluacji.
4. Wykonaj testy w przeglądarce
Udostępnij każdy wariant i sprawdź, czy:
- Wbudowane wyszukiwanie nadal się otwiera i zwraca oczekiwany wynik w dokumentacji.
- Nawigacja instant Material zmienia trasy bez duplikowania loadera widgetu.
document.querySelectorAll('#chattybox-widget').lengthpozostaje równe1po kilku zmianach tras.- Przy widoku o szerokości 390 px launcher nie zasłania wyszukiwania, nawigacji ani przycisków poprzedniej/następnej strony.
- Obsługiwane pytanie cytuje oczekiwaną stronę, a pytanie spoza obsługiwanego zakresu skutkuje zachowawczą odpowiedzią awaryjną.
Pierwsze cztery testy sprawdzają działanie integracji. Piąty zależy od stron, które indeksujesz, i wymaga reprezentatywnego zestawu ewaluacyjnego; postępuj zgodnie z przewodnikiem po scrapingu oraz listą kontrolną uruchomienia, zamiast traktować pomyślne załadowanie skryptu jako dowód jakości odpowiedzi.
5. Zachowaj restrykcyjną CSP
Zezwól na hosta widgetu w script-src, skonfigurowane źródło API w connect-src, a w razie potrzeby także na źródła czcionek w style-src i font-src. Bieżący widget wstrzykuje style komponentów, dlatego nawet skądinąd restrykcyjna polityka wymaga jawnej strategii dla stylów wbudowanych. Unikaj wieloznacznych list źródeł.
Lista kontrolna utrzymania
Po aktualizacji MkDocs lub Material ponownie zbuduj oba warianty motywu, ponieważ nazwy bloków szablonów nadrzędnych mogą się zmienić. Zachowaj stały identyfikator skryptu, nie usuwaj super() i ponownie wykonaj testy wyszukiwania, nawigacji instant, nakładania się elementów na urządzeniach mobilnych oraz cytowania źródeł.
Do planowania wdrożenia od początku do końca użyj listy kontrolnej implementacji chatbota dla dokumentacji.