Как добавить ИИ-чат-бот Asyntai в Docusaurus

Пошаговое руководство для документационных сайтов на Docusaurus

Платформа:

Шаг 1: Получите код встраивания

Сначала перейдите на Панель управления Asyntai и прокрутите вниз до раздела «Код для встраивания». Скопируйте уникальный код, который выглядит так:

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

Примечание: Код выше — всего лишь пример. Вы должны скопировать свой уникальный код для встраивания с вашей Панели управления, так как он содержит ваш персональный идентификатор виджета.

Шаг 2: Добавьте скрипт в docusaurus.config.js (рекомендуется)

Лучший способ добавить чат-бот на все страницы вашего сайта на Docusaurus — через конфигурационный файл:

Откройте свой проект Docusaurus в редакторе кода
Найдите и откройте файл docusaurus.config.js в корне вашего проекта
Найдите объект const config = { }
Добавьте или обновите поле scripts, вставив виджет 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
};

Сохраните файл docusaurus.config.js
Пересоберите сайт, выполнив npm run build или yarn build
Перезапустите сервер разработки, если он запущен локально

Совет: Поле scripts принимает массив источников JavaScript. Тег скрипта будет автоматически вставлен в HTML head каждой страницы. Это самый чистый и удобный в обслуживании метод для сайтов на Docusaurus.

Альтернативный метод 1: строковый формат (более простой синтаксис)

Если вы предпочитаете более простой подход, вы можете использовать строковый формат в массиве scripts:

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

Примечание: При использовании строкового формата нужно изменить URL скрипта, добавив ID вашего виджета в качестве параметра запроса, или использовать объектный формат из шага 2, который позволяет напрямую задать атрибут data-asyntai-id.

Альтернативный способ 2: Теги в Head

Вы также можете добавить скрипт, используя поле headTags в 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,
      },
    },
  ],
};

Совет: Поле headTags предоставляет более точный контроль над HTML-тегами, вставляемыми в секцию <head>. Этот метод функционально эквивалентен использованию поля scripts.

Альтернативный метод 3: пользовательский HTML-шаблон (продвинутый)

Для продвинутых пользователей доступен режим разработчика для прямого добавления кода в HTML:

Создайте новую директорию: src/theme (если она не существует)
Создайте файл: src/theme/Root.js
Добавьте следующий код для динамического внедрения скрипта:

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}</>;
}

Сохраните файл и пересоберите сайт

Важно: Компонент Root.js оборачивает всё ваше приложение. Этот продвинутый метод следует использовать только при необходимости в пользовательской JavaScript-логике или при наличии специфических требований, которые нельзя реализовать через конфигурационный файл.

Альтернативный способ 4: Swizzle Footer

Вы можете настроить нижний колонтитул, чтобы включить скрипт:

Выполните команду swizzle: npm run swizzle @docusaurus/theme-classic Footer -- --eject
Это создаёт копию компонента Footer в src/theme/Footer/
Отредактируйте компонент Footer, чтобы включить ваш тег скрипта
Добавьте скрипт перед закрывающим тегом футера
Сохраните и пересоберите ваш сайт

Примечание: Swizzling даёт вам полный контроль над компонентами Docusaurus, но вам придётся самостоятельно поддерживать этот компонент. Обновления Docusaurus не будут автоматически обновлять swizzled-компоненты.

Шаг 3: Сборка и развёртывание

После добавления кода соберите и задеплойте свой сайт Docusaurus:

# Build the site
npm run build

# Or with Yarn
yarn build

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

Совет: В процессе разработки запустите npm start или yarn start для предварительного просмотра изменений локально. Чат-бот должен появиться в правом нижнем углу на всех страницах.

Шаг 4: Проверка установки

После деплоя изменений откройте сайт документации в новой вкладке браузера. Вы должны увидеть кнопку виджета чата в правом нижнем углу. Нажмите на неё, чтобы убедиться, что всё работает.

Виджет не отображается? Убедитесь, что вы пересобрали сайт после внесения изменений. Проверьте, что вы заменили YOUR_WIDGET_ID на фактический ID виджета из панели управления. Очистите кэш браузера или откройте сайт в режиме инкогнито. Откройте консоль браузера (F12) для проверки ошибок JavaScript.

Документация