Przejdź do głównej treści
ChattyBoxZacznij bezpłatnie

Dodaj chatbota AI z cytowaniami do MkDocs

· 4 minuty czytania
Michael Fisher
Michael Fisher
ChattyBox maintainer and technical writer

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. Stały identyfikator pomaga zliczyć ten skrypt; nie wykrywa innego loadera z innym identyfikatorem lub bez niego.

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​

Pobierz i rozpakuj przykłady MkDocs, a następnie uruchom poniższe polecenia z rozpakowanego katalogu examples/mkdocs-chattybox. Zawiera on plik requirements.txt oraz osobne projekty material i vanilla. W istniejącym projekcie użyj zamiast tego jego własnych zależności i katalogu projektu.

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:

  1. Wbudowane wyszukiwanie nadal się otwiera i zwraca oczekiwany wynik w dokumentacji.
  2. Nawigacja instant Material zmienia trasy bez duplikowania loadera widgetu.
  3. document.querySelectorAll('#chattybox-widget').length pozostaje równe 1 po kilku zmianach tras.
  4. Przy widoku o szerokości 390 px launcher nie zasłania wyszukiwania, nawigacji ani przycisków poprzedniej/następnej strony.
  5. Odpowiedź na obsługiwane pytanie cytuje oczekiwaną stronę; sprawdź, czy pytania spoza obsługiwanego zakresu prowadzą do zachowawczej odpowiedzi awaryjnej, nie zakładając, że asystent zawsze powstrzyma się od odpowiedzi.

Zliczanie identyfikatora obejmuje tylko ten skrypt; sprawdź również inne integracje i wyrenderowany widget pod kątem duplikatów. 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 oraz źródło obrazu każdej niestandardowej ikony w img-src. W przypadku widgetu v16 z aktualnego kodu źródłowego zezwól na źródła Google Fonts w style-src i font-src, gdy wstrzykiwany jest arkusz stylów Inter; sprawdź działanie wdrożonego loadera. 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.

Źródła​