Jak dodać chatbota AI Asyntai do Docusaurus

Instrukcja krok po kroku dla stron dokumentacji Docusaurus

Platforma:

Krok 1: Pobierz swój kod osadzania

Najpierw przejdź do swojego Panelu Asyntai i przewiń w dół do sekcji "Kod osadzania". Skopiuj swój unikalny kod osadzania, który będzie wyglądał tak:

<script async src="https://asyntai.com/static/js/chat-widget.js" data-asyntai-id="YOUR_WIDGET_ID"></script>

Uwaga: Powyższy kod to tylko przykład. Musisz skopiować swój własny unikalny kod osadzania z Panelu, ponieważ zawiera on Twój osobisty identyfikator widgetu.

Krok 2: Dodaj skrypt do docusaurus.config.js (zalecane)

Najlepszym sposobem dodania chatbota do wszystkich stron witryny Docusaurus jest plik konfiguracyjny:

Otwórz projekt Docusaurus w edytorze kodu
Znajdź i otwórz plik docusaurus.config.js w katalogu głównym projektu
Znajdź obiekt const config = { }
Dodaj lub zaktualizuj pole scripts z widgetem Asyntai:

const config = {
  // ... other config options

  scripts: [
    // Other scripts if any
    {
      src: 'https://asyntai.com/static/js/chat-widget.js',
      'data-asyntai-id': 'YOUR_WIDGET_ID',
      async: true,
    },
  ],

  // ... rest of config
};

Zapisz plik docusaurus.config.js
Przebuduj witrynę, uruchamiajac npm run build lub yarn build
Uruchom ponownie serwer deweloperski, jeśli działa lokalnie

Wskazówka: Pole scripts akceptuje tablice zrodel JavaScript. Tag script zostanie automatycznie wstawiony do sekcji HTML head na każdej stronie. Jest to najczystsza i najlatwiejsza w utrzymaniu metoda dla witryn Docusaurus.

Metoda alternatywna 1: Format tekstowy (prostsza składnia)

Jeśli wolisz prostsze podejście, możesz użyć formatu tekstowego w tablicy scripts:

const config = {
  scripts: [
    'https://asyntai.com/static/js/chat-widget.js',
  ],
};

Uwaga: W przypadku formatu tekstowego konieczna będzie modyfikacja adresu URL skryptu w celu dodania identyfikatora widgetu jako parametru zapytania lub użycie formatu obiektowego pokazanego w Kroku 2, który umożliwia bezpośrednie ustawienie atrybutu data-asyntai-id.

Metoda alternatywna 2: Niestandardowe tagi Head

Możesz również dodać skrypt, używając pola headTags w pliku docusaurus.config.js:

const config = {
  headTags: [
    {
      tagName: 'script',
      attributes: {
        src: 'https://asyntai.com/static/js/chat-widget.js',
        'data-asyntai-id': 'YOUR_WIDGET_ID',
        async: true,
      },
    },
  ],
};

Wskazówka: Pole headTags zapewnia większą kontrolę nad dokladnymi tagami HTML wstawianymi do sekcji <head>. Ta metoda jest funkcjonalnie rownowazna z uzyciem pola scripts.

Metoda alternatywna 3: Niestandardowy szablon HTML (zaawansowana)

Dla zaawansowanych użytkowników, którzy potrzebują pełnej kontroli nad szablonem HTML:

Utwórz nowy katalog: src/theme (jeśli nie istnieje)
Utwórz plik: src/theme/Root.js
Dodaj poniższy kod, aby dynamicznie wstrzyknąć skrypt:

import React, { useEffect } from 'react';

export default function Root({children}) {
  useEffect(() => {
    const script = document.createElement('script');
    script.src = 'https://asyntai.com/static/js/chat-widget.js';
    script.setAttribute('data-asyntai-id', 'YOUR_WIDGET_ID');
    script.async = true;
    document.head.appendChild(script);

    return () => {
      // Cleanup when component unmounts
      document.head.removeChild(script);
    };
  }, []);

  return <>{children}</>;
}

Zapisz plik i przebuduj witrynę

Ważne: Komponent Root.js opakowuje całą aplikację. Ta zaawansowana metoda powinna być używana tylko wtedy, gdy potrzebujesz niestandardowej logiki JavaScript lub masz specyficzne wymagania, których nie można spełnić za pomocą podejścia z plikiem konfiguracyjnym.

Metoda alternatywna 4: Swizzle komponentu Footer

Możesz dostosować stopkę, aby zawierała skrypt:

Uruchom polecenie swizzle: npm run swizzle @docusaurus/theme-classic Footer -- --eject
Tworzy to kopię komponentu Footer w src/theme/Footer/
Edytuj komponent Footer, aby zawierał Twój tag script
Dodaj skrypt przed zamykającym tagiem stopki
Zapisz i przebuduj witrynę

Uwaga: Swizzling daje pełną kontrolę nad komponentami Docusaurus, ale oznacza to, że będzie trzeba samodzielnie utrzymywać ten komponent. Aktualizacje Docusaurus nie będą automatycznie aktualizować komponentów poddanych swizzlingowi.

Krok 3: Budowanie i wdrożenie

Po dodaniu kodu zbuduj i wdróż witrynę Docusaurus:

# Build the site
npm run build

# Or with Yarn
yarn build

# Deploy to your hosting platform
# (Vercel, Netlify, GitHub Pages, etc.)

Wskazówka: Podczas programowania uruchom npm start lub yarn start, aby podejrzeć zmiany lokalnie. Chatbot powinien pojawić się w prawym dolnym rogu na wszystkich stronach.

Krok 4: Weryfikacja instalacji

Po wdrożeniu zmian otwórz witrynę dokumentacji w nowej karcie przeglądarki. Przycisk widgetu czatu powinien być widoczny w prawym dolnym rogu. Kliknij go, aby upewnić się, że otwiera się i działa poprawnie.

Nie widzisz widgetu? Upewnij się, że przebudowałeś witrynę po wprowadzeniu zmian. Sprawdź, czy zamieniłeś YOUR_WIDGET_ID na rzeczywisty identyfikator widgetu z panelu sterowania. Wyczyść pamięć podręczną przeglądarki lub otwórz stronę w trybie incognito. Otwórz konsolę przeglądarki (F12), aby sprawdzić, czy nie ma błędów JavaScript.

Dokumentacja