Документация Base управляется сообществом. Мы приветствуем и поощряем вклад каждого, чтобы поддерживать эти документы точными, полезными и актуальными.

Примечание: Этот репозиторий используется для публичного сайта документации Base. Контент находится в папке docs/.

Локальная разработка

Предварительное требование: Node.js v19+.

1. Клонируйте репозиторий.
2. Установите Mint CLI для локального просмотра изменений документации:

npm i -g mint

3. Просмотр локально (запустите из директории docs/, где находится docs.json):

cd docs
mint dev

Альтернативно, без глобальной установки:

npx mint dev

Устранение неполадок

• Убедитесь, что установлена Node.js версии 19 или выше, и что вы запускаете команду mint dev из каталога, содержащего файл docs.json (обычно это папка docs/).
• Локальный просмотр отличается от продакшена: выполните mint update для обновления CLI.

Как внести вклад

1. Fork and branch (Сделайте форк и ветку): Сделайте форк base/docs и создайте описательную ветку для ваших изменений.
2. Edit content in docs/ (Редактируйте контент в docs/): Следуйте структуре и стилю, указанным ниже. Просматривайте изменения локально с помощью Mint CLI.
3. Open a pull request (Откройте pull request): Предоставьте четкое описание и ссылки на связанные страницы. Команда документации и сообщество проведут ревью.

Совет: Отдавайте предпочтение небольшим, сфокусированным PR (Pull Request). Связывайте связанные руководства и ссылки непосредственно в вашем контенте.

Структура документации

Основной принцип: сохраняйте существующую структуру

Предупреждение: Не создавайте новые разделы верхнего уровня. Размещайте весь новый контент в существующих папках внутри docs/.

Документация Base организована в установленные разделы (например: get-started/, learn/, base-account/, base-app/, base-chain/, cookbook/, mini-apps/, onchainkit/). Размещайте новый контент в наиболее подходящем существующем разделе.

Политика навигации

Примечание: Мы обычно не меняем глобальную навигацию (вкладки верхнего уровня) или разделы боковой панели, если нет четкой, широко полезной необходимости. Вклад должен быть сосредоточен на улучшении существующих страниц и добавлении новых страниц в текущих разделах.

Назначение и размещение разделов

• Quickstart (Быстрый старт): Полная настройка до первого успеха. Сохраняйте лаконичность и актуальность.
• Concepts (Концепции): Объяснения компонентов, архитектуры и философии дизайна.
• Guides (Руководства): Пошаговые, ориентированные на действие туториалы для конкретных задач.
• Examples (Примеры): Полные, запускаемые примеры, демонстрирующие реальное использование.
• Technical Reference (Техническая справка): Спецификации API/методов/компонентов с параметрами и типами возвращаемых значений.
• Contribute (Вклад): Информация для контрибьюторов и обновления процессов.

Область применения Cookbook

• Раздел cookbook/ содержит руководства и паттерны, ориентированные на варианты использования, а не на документацию по конкретным продуктам.
• Отдавайте предпочтение комплексным решениям, демонстрирующим, как создавать проекты на Base с использованием различных инструментов и сценариев.

Предупреждение: Избегайте разрастания подразделов:

• Размещайте все руководства на одном уровне внутри раздела Guides.
• Организуйте Reference по компонентам/функциям, а не по вариантам использования.
• Используйте перекрестные ссылки вместо добавления новых структурных слоев.

Стиль и форматирование

Стиль написания

1. Будьте краткими и последовательными; используйте активный залог и второе лицо.
2. Сосредоточьтесь на основном сценарии; кратко упоминайте альтернативы там, где это уместно.
3. Используйте явные, описательные заголовки и имена файлов.
4. Сохраняйте единообразную терминологию; вводите сокращения при первом использовании.

Контент, удобный для ИИ

• Используйте ясный, однозначный язык и напрямую связывайте связанные страницы.
• Предпочитайте маркированные списки для опций/шагов, когда они не являются последовательными.
• Явно называйте и ссылайтесь на библиотеки и инструменты.
• Используйте семантические, читаемые URL и избегайте неоднозначных сокращений.

Контрольный список:

• Поймёт ли большая языковая модель этот контент и сможет ли корректно следовать ему?
• Может ли инженер скопировать, вставить и запустить примеры как есть?

Форматирование Mintlify

• Начинайте основные разделы с H2 (##) и подразделы с H3 (###).
• Используйте блоки кода с указанием языка и необязательным именем файла.
• Оберните изображения в и добавьте alt текст.
• Используйте callouts для выделения: <Note>, <Tip>, <Warning>, <Info>, <Check>.
• Для процедур предпочитайте <Steps> / <Step>.
• Для альтернатив используйте <Tabs> / <Tab>.
• Для документации API используйте <ParamField>, <ResponseField> и примеры запросов/ответов.

Примеры кода

• Предоставляйте полные, запускаемые примеры с реалистичными данными.
• Включайте правильную обработку ошибок и граничные случаи.
• Указывайте язык и имя файла, когда это полезно.
• Показывайте ожидаемый вывод или шаги проверки.

Политика сторонних руководств

Предупреждение: Мы обычно не принимаем руководства, которые в основном документируют сторонний продукт. Исключения требуют четкого варианта использования, ориентированного на Base, и тесной интеграции с продуктами Base. Простое развертывание на Base или подключение к Base Account/Base App недостаточно.

Если ваша цель - повысить видимость вашего продукта, пожалуйста, запросите включение на странице Base Ecosystem вместо этого. Смотрите инструкции по обновлению страницы Base Ecosystem.

Контрольный список для проверки (перед отправкой PR)

• Соответствует существующей структуре (без новых разделов верхнего уровня)
• Только минимальные, необходимые подразделы
• Единообразная терминология; сокращения вводятся при первом использовании
• Примеры кода должны быть полными, корректно выполняться и проходить проверку.
• Включены перекрестные ссылки на связанные руководства/примеры/справочники
• Корректно использует компоненты Mintlify и иерархию заголовков
• Доступные изображения с описательным alt текстом и фреймами
• Удобно для ИИ: явный, богатый ссылками и легкий для понимания

Процесс отправки

1. Создайте PR (pull request) в https://github.com/base/docs с вашими изменениями.
2. Включите четкое описание изменений и затронутых страниц.
3. Запросите ревью у команды документации.
4. Учитывайте обратную связь и итерируйте.
5. После одобрения изменения будут объединены и опубликованы.

Публикация изменений

Основная команда просматривает открытые PR. Время обработки (SLA) составляет 2 недели — обычно в порядке очереди, за исключением срочных изменений.

Storybook для UI компонентов

Смотрите storybook/README.md для деталей о локальном Storybook и документации компонентов.