Docsbook
Обзор

Управление документацией

Как работать с документацией после создания вашего сайта.

Float Widget — Managing Your Site#

Когда вы вошли в систему и просматриваете свой сайт, в правом нижнем углу появляется виджет управления.

┌──────────────────────┐
│ 👤 Your Name         │
│                      │
│ ✨ Premium / Free    │
│                      │
│ ⚙️ Settings          │
│ 🚪 Sign Out          │
└──────────────────────┘

Нажмите на аватар или настройки#

Откроется меню с опциями управления.

Что можно настроить?#

1. Основные настройки#

  • Имя рабочего пространства — отображается в вашем профиле
  • Статус подписки — Free или Premium
  • Язык сайта — язык по умолчанию

2. Домен#

(Только для премиум-подписки)

  • Если у вас есть собственный домен — укажите его здесь
  • Вместо docsbook.io/user/repo у вас будет docs.example.com

Подробнее: Настройка собственного домена

3. Внешний вид#

Параметры отображения:

  • Скрыть "Powered by Docsbook" (Premium)

    • Удаляет значок внизу страницы
    • Делает сайт полностью вашим

  • Тема (скоро)

    • Светлая / Темная тема
    • Будет добавлено в будущем

4. Языки & Перевод#

(Только для премиум-подписки)

  • Включить автоматический перевод
  • Выбрать языки
  • Документация переводится автоматически

Подробнее: Перевод Документов

5. Опасные действия#

⚠️ Удалить рабочее пространство

Нажмите «Удалить рабочее пространство», чтобы:

  • Удалить все настройки
  • Отключить сайт документации
  • Это действие необратимо!

Ваш репозиторий GitHub не будет удален, только сайт документации.

Как обновить документацию?#

Метод 1: Веб-интерфейс GitHub#

  1. Откройте ваш репозиторий на github.com
  2. Отредактируйте файл markdown
  3. Нажмите "Commit changes"
  4. Обновления появятся на вашем сайте Docsbook

Метод 2: Git Локально#

# 1. Clone the repository
git clone https://github.com/username/repo.git
cd repo
 
# 2. Edit files
nano docs/getting-started.md
 
# 3. Stage changes
git add docs/
 
# 4. Make a commit
git commit -m "Update documentation"
 
# 5. Push to GitHub
git push origin main

Обновления появляются на сайте автоматически!

Метод 3: Добавить новую страницу#

  1. Создайте новый .md файл в вашем репозитории
  2. Напишите контент
  3. Зафиксируйте изменения
  4. Файл появляется в меню сайта

Пример:

# Create new file
echo "# API Reference" > docs/api/reference.md
 
# Add content
echo "Your API documentation..." >> docs/api/reference.md
 
# Commit
git add docs/api/reference.md
git commit -m "Add API reference"
git push origin main

Метод 4: Удалить Страницу#

  1. Удалите файл из репозитория GitHub
  2. Зафиксируйте удаление
  3. Страница исчезнет с сайта

Проверка синхронизации#

Почему мой сайт не обновился?#

Обновления не происходят мгновенно, проверьте:

  1. Убедитесь в наличии коммита в GitHub

    • Откройте github.com → ваш репозиторий
    • Вы видите новый коммит?
    • Если нет — обновите локально

  2. Обновите страницу

    • Нажмите Ctrl+F5 (или Cmd+Shift+R на Mac)
    • Это очистит кеш браузера

  3. Подождите 1-2 минуты

    • Синхронизация не мгновенна
    • Docsbook периодически проверяет GitHub

  4. Проверьте интернет

    • Убедитесь, что у вас есть интернет
    • Проверьте, открыт ли репозиторий

Проблемы с синхронизацией?#

Файлы не отображаются в меню:

  • Убедитесь, что файлы .md
  • Проверьте имена — только латинские буквы, цифры, дефисы

Некоторые файлы обновились, другие нет:

  • Возможно, проблема в кэше браузера
  • Очистите кэш с помощью Ctrl+F5

Старая версия везде:

  • Подождите 5 минут
  • Очистите кэш браузера

Структурирование Документации#

Как организовать файлы?#

Боковая панель создается на основе структуры папок. Организуйте логически:

Вариант 1: По категориям

docs/
├── README.md
├── getting-started.md
├── api/
│   ├── overview.md
│   ├── auth.md
│   └── endpoints.md
└── guides/
    ├── deployment.md
    └── troubleshooting.md

Вариант 2: По уровню детализации

docs/
├── README.md
├── 1-basics.md
├── 2-intermediate.md
├── 3-advanced.md
└── faq.md

Мы рекомендуем Вариант 1 — более понятная структура.

[See API](/ru/docs/guides/getting-started/api/overview)
[Start here](/ru/docs/guides/getting-started/getting-started)
[FAQ](/ru/docs/guides/getting-started/../faq)

Эти ссылки автоматически преобразуются в корректные ссылки на страницы сайта.

[Go to installation](#installation)

Для этого в другом месте файла должен быть этот заголовок:

## Installation
 
Installation instructions...

Изображения & Медиа#

Как добавить изображения?#

  1. Добавить изображение в папку (например, docs/images/screenshot.png)
  2. Загрузить в GitHub
  3. Ссылка в markdown:
![Description](https://raw.githubusercontent.com/docsbook-io/docs/main/guides/getting-started/./images/screenshot.png)

Где хранить изображения?#

Создайте папку:

docs/
├── README.md
├── images/
│   ├── screenshot.png
│   ├── architecture.jpg
│   └── diagram.gif
└── guides/

Форматы#

Поддерживаемые:

  • PNG (лучше всего)
  • JPG (для фотографий)
  • GIF (анимация)
  • WebP (современный формат)

Кто может видеть мою документацию?#

Open Access#

Ваш сайт документации открыт для всех — даже если репозиторий является приватным.

Кто его видит:

  • ✅ Все в интернете
  • ✅ Боты поисковых систем (Google, Bing)
  • ✅ Люди без учетной записи GitHub

Это хорошо — ваша документация доступна везде!

Только вы видите настройки#

Виджет управления виден только вам, когда вы вошли в систему.

Другие люди видят только:

  • Ваш сайт документации
  • Прекрасный дизайн
  • Контент
  • Они не видят: кнопки управления, настройки, опции

Совместная работа над документацией#

Как работать вместе?#

Если над документацией работает несколько человек:

  1. Добавьте их в репозиторий GitHub — они смогут редактировать
  2. Любой может обновить документацию — отправляя pull requests
  3. Docsbook автоматически обновляет сайт — как только изменения объединяются в основную ветку

Workflow#

Colleague 1         Colleague 2         Docsbook Site
    ↓                   ↓                    ↓
Edits          →   Pull Request    →   Updates
Documentation      (Code Review)       Automatically

Версионирование документации#

⚠️ Пока не поддерживается, но запланировано.

В настоящее время хранится только последняя версия.

Если вам нужны разные версии:

  • Используйте ветки Git (docs/v1, docs/v2)
  • Или создайте отдельные репозитории

Аналитика#

Как я могу узнать, кто читает мою документацию?#

(Будет добавлено в ближайшее время)

На данный момент вы можете:

  1. Настроить Google Analytics
  2. Отслеживать трафик на вашем домене
  3. Увидеть, какие страницы наиболее популярны

Свяжитесь с support@docsbook.io для получения помощи в настройке.

Следующие шаги#

Работает на Docsbook