Как добавлять блоки контента в GitBook

Краткое описание и цель

GitBook — платформа для совместного создания документации, использующая идеи контроля версий: ветвление, слияние и черновики. Она позволяет нескольким авторам одновременно работать над сайтом документации, хранить отдельные черновики и просматривать различия между текущей версией и основной копией.

В этой статье описаны доступные типы блоков контента и подробные инструкции по их добавлению. Также приведены практические рекомендации по оформлению, роли в рабочем процессе, критерии приёмки и лайфхаки для повышения качества документации.

Что такое блоки контента в GitBook

Блоки контента — это строительные элементы страницы. Типичные блоки:

• Заголовки и параграфы
• Маркированные и нумерованные списки
• Кодовые блоки
• Изображения и файлы
• Подсказки (hint) с разными иконками и уровнем важности
• Таблицы с настраиваемыми типами столбцов
• Блоки-ссылки на страницы

Определение: черновик — версия страницы, над которой вы работаете отдельно от основной (master) копии. Слияние — процесс объединения изменений из черновика в основную версию.

Быстрая навигация по добавлению блоков

• Чтобы открыть список блоков — кликните в любом месте страницы и нажмите кнопку plus (+).
• Чтобы добавить конкретный блок — начните печатать название блока или найдите его в выпадающем меню.
• Многие блоки автоматически применяют форматирование после выбора.

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

Как добавлять параграфы, списки, цитаты и кодовые блоки

Чтобы добавить базовый контент (параграф, список, цитату, код):

1. Кликните в нужное место страницы.
2. Нажмите кнопку plus (+), чтобы открыть выпадающее меню контент-блоков.
3. В списке выберите тип простого блока: Paragraph, List, Quote или Code.
4. GitBook автоматически применит соответствующее форматирование.

Совет: используйте Markdown для быстрого форматирования — это удобно для совместимости и версии в репозитории.

Когда это не работает

• Если блок не появляется в меню, проверьте права доступа на странице.
• Если формат не сохраняется, проверьте конфликт между черновиком и основной веткой.

Как добавлять изображения и файлы

Добавление изображений и вложений похоже, но у каждого типа есть свои вкладки и настройки.

1. Откройте страницу и поставьте курсор в место, где хотите вставить медиа.
2. Нажмите plus (+) и выберите опцию Images или Insert Files.
3. В правой панели выберите вкладку Files, URL или Unsplash для поиска стоковых изображений без атрибуции.
4. Загрузите файл или вставьте ссылку. После вставки кликните по трём точкам в левом верхнем углу блока, чтобы изменить выравнивание, удалить изображение или добавить подпись.

Для файлов:

1. Нажмите Insert files в меню контент-блоков.
2. В правой панели нажмите Browse files и выберите файл на компьютере.
3. Кликните по файлу в списке — GitBook создаст блок вложения, клик по которому скачивает файл.

Практика: оптимизируйте изображения по размеру и названию файла перед загрузкой. Подпись и alt-текст помогают доступности и SEO.

Когда использовать URL вместо загрузки

• Если изображение обновляется у внешнего провайдера
• Если используете CDN или общую библиотеку изображений

Как добавлять подсказки

Подсказки (hints) выделяют важную информацию и имеют четыре типа: information, success, warning, danger.

1. Нажмите plus (+) и выберите Hint.
2. GitBook вставит подсказку с типом по умолчанию — information (синий значок).
3. Чтобы сменить тип, кликните по иконке подсказки — она будет переключать варианты: information → success → warning → danger.

Рекомендации:

• Используйте danger только для действий, которые могут привести к потере данных.
• success — для подтверждения успешного завершения шага.
• Не перегружайте страницу подсказками; старайтесь, чтобы они были релевантны.

Как добавлять таблицы

Таблицы в GitBook гибкие: вы можете добавлять строки, столбцы и менять типы данных в столбцах.

1. Нажмите plus (+) и выберите Table.
2. Нажмите на заголовок столбца, чтобы открыть мини-меню изменения имени и других опций.
3. По умолчанию тип столбца — Text. Нажмите кнопку с буквой T, чтобы выбрать другой тип: Number, Checkbox, Dropdown, File, Rating и др.
4. Кликните по иконке из шести точек в верхнем левом углу таблицы, чтобы вставить строки/столбцы, удалить таблицу или изменить её свойства.

Советы по дизайну таблиц:

• Используйте осмысленные заголовки столбцов.
• Ограничивайте количество столбцов для мобильной читабельности.
• Для больших наборов данных используйте CSV/экспорт и храните ссылку на файл.

Как добавлять блоки-ссылки на страницы

Блок-ссылка занимает всю строку и привлекает внимание к важным страницам.

1. Нажмите plus (+) и выберите Page Link.
2. Выберите страницу, на которую будет вести ссылка, из появившегося списка.
3. Блок появится как отдельная строка с заголовком и кратким описанием.

Когда использовать блок-ссылку

• Для ссылок на руководства по запуску, контрольные списки или важные процессы.

Практический рабочий процесс и роли

Ниже приведён минимальный SOP для работы с блоками в команде и роль‑базовые чек-листы.

Мини‑методология добавления контента (быстрый цикл):

1. Автор создаёт черновик и добавляет блоки.
2. Локальная проверка: орфография, форматирование, alt-тексты у изображений.
3. Ревьюер проверяет содержание и соответствие стилю.
4. Слияние в основную ветку после одобрения.
5. Теги/заметки о релизе и проверка на проде.

Чек-лист для автора:

• Заголовки соответствуют шаблону стиля.
• Alt-тексты у всех изображений описательны и на русском языке.
• Таблицы имеют корректные типы данных.
• Подсказки используются только при необходимости.
• Файлы оптимизированы по размеру.

Чек-лист для ревьюера:

• Проверить факты и кодовые примеры.
• Проверить единообразие терминологии.
• Проверить права доступа и ссылки.
• Прогнать страницу через быстрый просмотр в мобильной версии.

Чек-лист для владельца раздела:

• Оценить необходимость обновления связанных страниц.
• Планировать регулярную ревизию контента.
• Контролировать теги и метаданные для поиска.

Дерево решений для выбора типа блока

Используйте простое дерево решений, чтобы быстро выбрать блок. Ниже — схема в формате Mermaid.

flowchart TD
  A[Нужно показать простой текст?] -->|Да| B[Параграф или Заголовок]
  A -->|Нет| C[Это изображение, файл или ссылка?]
  C -->|Изображение| D[Images]
  C -->|Файл| E[Insert Files]
  C -->|Ссылка на страницу| F[Page Link]
  A2[Нужно структурировать данные?] -->|Да| G[Table]
  A2 -->|Нет| H[Подсказка или кодовый блок]
  H -->|Подсказка| I[Hint]
  H -->|Код| J[Code Block]

Частые ошибки и как их избежать

• Ошибка: неописанные изображения. Решение: всегда заполняйте alt.
• Ошибка: слишком большие файлы. Решение: оптимизируйте и отдавайте через CDN.
• Ошибка: несогласованные типы в таблицах. Решение: заранее согласуйте схему столбцов.
• Ошибка: слишком много подсказок подряд. Решение: используйте подсказки экономно и по сути.

Критерии приёмки

• Страница отображается корректно в десктопной и мобильной версиях.
• Все изображения имеют alt и подписи при необходимости.
• Таблицы читаются и фильтруются при необходимости.
• Файлы корректно скачиваются по клику.
• Текст соответствует стилю и терминологии проекта.

Короткий глоссарий

• Черновик — отдельная версия страницы для работы до слияния.
• Слияние — объединение изменений с основной копией.
• Hint — заметка/подсказка с иконкой для привлечения внимания.
• Page Link — блок, ведущий на другую страницу и занимающий отдельную строку.

Когда GitBook может не подойти

• Если вам нужна полнофункциональная CMS с расширенной работой с пользователями и ролевой моделью на уровне ERP, GitBook может оказаться недостаточно гибким.
• Для больших наборов данных и аналитики лучше использовать специализированные БД или инструменты отчетности.

Советы по локализации и доступности

• Пишите короткими предложениями и используйте маркеры.
• Переводите интерфейсные описания и подписи, но сохраняйте оригинальные имена функций в кодовых примерах.
• Обязательно добавляйте alt-теги для изображений и тестируйте страницы с экранными читалками.

Итог и рекомендации

GitBook упрощает совместную работу над документацией за счёт знакомых концепций контроля версий и удобных блоков контента. Следуйте простым правилам оформления: краткие заголовки, понятные alt-тексты, согласованные таблицы и минимальное использование подсказок.

Важно: начните с шаблона для каждого раздела и настраивайте чек-листы для ваших ролей. Это ускорит создание и улучшит качество документации.

Краткое резюме:

• Используйте выпадающее меню plus для доступа к блокам.
• Оптимизируйте изображения и заполняйте alt.
• Применяйте чек-листы и процесс ревью.

Спасибо за внимание. Если нужен шаблон страницы, чек-листы в формате Markdown или пример структуры раздела — я могу подготовить их отдельно.