Přidejte AI chatbota s citacemi zdrojů do MkDocs

Témata MkDocs používají různé adresáře override a Material může mezi stránkami přecházet bez úplného načtení. Odolná integrace musí zachovat existující skripty tématu, načíst widget právě jednou a spolupracovat s vyhledáváním a mobilní navigací.

Autor a technický recenzent: Michael Fisher, správce ChattyBoxu. Publikováno a technicky ověřeno 10. července 2026. Níže uvedený ověřovací protokol je návodem k implementaci; neplyne z něj žádný nárok na návštěvnost, míru odklonu ani přesnost odpovědí.

1. Vyberte správný adresář override

Pro Material for MkDocs nastavte custom_dir na adresář overrides:

site_name: My documentation
theme:
  name: material
  custom_dir: overrides
  features:
    - navigation.instant

Pro vestavěné téma použijte samostatný adresář vlastního tématu:

site_name: My documentation
theme:
  name: mkdocs
  custom_dir: custom_theme

Oddělení variant jasně ukazuje, která původní základní šablona se rozšiřuje.

2. Rozšiřte blok scripts

Pro Material vytvořte overrides/main.html, pro vestavěné téma custom_theme/main.html:

{% 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() }} zachovává skripty poskytované tématem včetně chování navigace a vyhledávání. Jeho vynechání může způsobit, že widget bude zdánlivě fungovat, ale potichu rozbije rozhraní dokumentace. Stabilní ID vám také poskytne přímou kontrolu duplicitního loaderu.

Použijte hodnoty specifické pro projekt z reference instalace widgetu. Průvodce AI chatbotem pro MkDocs popisuje rozsah zdrojů, chování scrapingu a otázky, které je třeba před publikováním vyhodnotit.

3. Sestavte obě varianty

Ze svého projektu MkDocs spusťte:

python -m venv .venv
. .venv/bin/activate
pip install -r requirements.txt

cd material
mkdocs build --strict

cd ../vanilla
mkdocs build --strict

--strict mění varování na chyby, takže zachytí rozbitou navigaci a problémy s konfigurací ještě před vyhodnocením widgetu.

4. Proveďte kontroly v prohlížeči

Spusťte obě varianty a ověřte:

1. Vestavěné vyhledávání se stále otevře a vrátí očekávaný výsledek v dokumentaci.
2. Okamžitá navigace Materialu mění trasy bez duplikace loaderu widgetu.
3. document.querySelectorAll('#chattybox-widget').length zůstává 1 i po několika změnách trasy.
4. Při viewportu 390 px spouštěč nezakrývá vyhledávání, navigaci ani ovládací prvky předchozí/další.
5. Podporovaná otázka cituje očekávanou stránku a nepodporovaná otázka vede ke konzervativnímu fallbacku.

První čtyři kontroly ověřují chování integrace. Pátá závisí na stránkách, které indexujete, a vyžaduje reprezentativní vyhodnocovací sadu; řiďte se průvodcem scrapingem a kontrolním seznamem spuštění namísto toho, abyste úspěšné načtení skriptu považovali za důkaz kvality odpovědí.

5. Zachovejte restriktivní CSP

V případě potřeby povolte hostitele widgetu v script-src, nakonfigurovaný origin API v connect-src a originy fontů v style-src a font-src. Aktuální widget vkládá styly komponent, takže i jinak striktní zásada potřebuje explicitní strategii pro inline styly. Vyhněte se seznamům zdrojů se zástupnými znaky.

Kontrolní seznam údržby

Po aktualizacích MkDocs nebo Materialu znovu sestavte obě varianty tématu, protože názvy bloků upstreamových šablon se mohou změnit. Zachovejte stabilní ID skriptu, ponechte super() a znovu proveďte kontroly vyhledávání, okamžité navigace, překrytí na mobilu a citací zdrojů.

Pro plánování nasazení od začátku do konce použijte kontrolní seznam implementace chatbota pro dokumentaci.

Zdroje

• Reference instalace widgetu ChattyBox
• Přizpůsobení témat MkDocs
• Přizpůsobení Material for MkDocs
• Průvodce Content Security Policy na MDN