Přejít na hlavní obsah
ChattyBoxZačít zdarma

Přidejte AI chatbota s citacemi zdrojů do MkDocs

· 4 min čtení
Michael Fisher
Michael Fisher
ChattyBox maintainer and technical writer

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 pomáhá spočítat tento skript; neodhalí jiný loader s odlišným nebo chybějícím ID.

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​

Stáhněte a rozbalte příklady pro MkDocs a poté spusťte následující příkazy z rozbaleného adresáře examples/mkdocs-chattybox. Obsahuje requirements.txt a samostatné projekty material a vanilla. U existujícího projektu místo toho použijte jeho vlastní závislosti a adresář.

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. Odpověď na podporovanou otázku cituje očekávanou stránku; u nepodporovaných otázek otestujte konzervativní fallback a nepředpokládejte, že se asistent vždy zdrží odpovědi.

Počet ID zahrnuje pouze tento skript; duplicity hledejte také v ostatních integracích a ve vykresleném widgetu. 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​

Povolte hostitele widgetu v script-src, nakonfigurovaný origin API v connect-src a origin obrázku případné vlastní ikony v img-src. U widgetu v16 z aktuálního zdrojového kódu povolte originy Google Fonts v style-src a font-src, když se vkládá jeho stylopis Inter; ověřte chování nasazeného loaderu. 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​