Docsbook
Обзор

Создание сайта документации

В этом руководстве вы узнаете, как настроить свой первый сайт документации на Docsbook — не требуется никакого опыта программирования. Каждый шаг включает скриншоты, чтобы вы всегда знали, куда нажимать.

Что вам понадобится#

Прежде чем начать, убедитесь, что у вас есть:

  • Компьютер с доступом в интернет — подойдет любая ОС (Windows, Mac, Linux)
  • Бесплатная учетная запись GitHub — здесь будут храниться ваши файлы документации

Если у вас еще нет учетной записи GitHub, перейдите на github.com и нажмите Sign up — это бесплатно и занимает около двух минут.

Что такое GitHub? GitHub — это популярный веб-сайт, где люди хранят и делятся файлами — особенно для документации и программных проектов. Представьте себе Google Drive, но специально разработанный для текстовых файлов и кода. Docsbook считывает ваши файлы из GitHub и превращает их в красивый веб-сайт документации.

Шаг 1 — Создайте учетную запись GitHub (пропустите, если у вас уже есть)#

  1. Перейдите по адресу github.com
  2. Нажмите Sign up в правом верхнем углу
  3. Введите свой адрес электронной почты и выберите пароль
  4. Выберите имя пользователя — оно будет отображаться в URL ваших документов (например, docsbook.io/your-username/your-repo)
  5. Подтвердите свой адрес электронной почты

Screenshot: GitHub homepage with Sign up button highlighted

Шаг 2 — Создайте репозиторий для вашей документации#

Что такое репозиторий? Репозиторий (или "repo") — это как папка на GitHub. Он хранит все ваши файлы документации. Вам понадобится один репозиторий для каждого сайта документации.

Option A — Start with an Example (Recommended for beginners)#

The easiest way to get started is to copy one of our ready-made example repositories. This is called forking — it creates your own personal copy of the repository that you can freely edit.

  1. Go to github.com/docsbook-io/docs

  2. You'll see a page with files and a description

    Screenshot: docsbook-io/docs repository page with Fork button visible in top-right

  3. Click the Fork button in the top-right corner of the page

    What does Fork mean? "Forking" means making your own personal copy of someone else's repository. It's like pressing "Duplicate" on a Google Doc. Your copy is completely independent — changes you make won't affect the original.

  4. A dialog appears. Leave all settings as they are and click Create fork

    Screenshot: Fork dialog with "Create fork" button highlighted

  5. After a moment, GitHub takes you to your new repository at github.com/YOUR-USERNAME/docs

    Screenshot: Your newly forked repository page

Done! You now have a repository with example documentation files ready to edit.

Option B — Start from Scratch#

Если вы предпочитаете начать с чистого листа:

  1. Убедитесь, что вы вошли в GitHub

  2. Перейдите по адресу github.com/new

    Screenshot: GitHub new repository form

  3. Заполните форму:

    • Название репозитория — выберите короткое имя без пробелов, например, my-docs или product-docs
    • Описание — необязательно, краткое описание того, что это
    • Видимость — выберите Public (Docsbook требует общедоступные репозитории)
    • Установите флажок Add a README file — это создаст вашу домашнюю страницу

  4. Нажмите Create repository

    Screenshot: Create repository button highlighted

  5. Открывается ваш новый репозиторий. Он содержит один файл: README.md

Шаг 3 — Подключите ваш репозиторий к Docsbook#

Теперь, когда у вас есть репозиторий GitHub, давайте подключим его к Docsbook, чтобы создать ваш сайт документации.

  1. Перейдите по адресу docsbook.io/connect

    Screenshot: Docsbook connect page with Sign in button

  2. Нажмите Sign in with GitHub

  3. GitHub попросит вас авторизовать Docsbook. Нажмите Authorize docsbook

    Docsbook только читает файлы вашего репозитория — он не может изменять или удалять что-либо.

  4. Вы увидите список ваших репозиториев. Найдите только что созданный и нажмите на него

    Screenshot: Repository list on Docsbook connect page with a repo highlighted

  5. Docsbook создает ваш сайт документации. Вы будете автоматически перенаправлены на него.

Ваш сайт документации теперь доступен по адресу:

docsbook.io/YOUR-GITHUB-USERNAME/YOUR-REPO-NAME

Шаг 4 — Редактирование Документации#

Существует три способа редактирования файлов документации. Выберите наиболее удобный.

Option A — Edit Directly on GitHub (Easiest, no setup needed)#

This is the simplest method. You edit files right in your browser on GitHub — no software to install.

Edit an existing page#

  1. Go to your repository on GitHub (e.g. github.com/YOUR-USERNAME/docs)

  2. Click on the file you want to edit, for example README.md

    Screenshot: Repository file list with README.md highlighted

  3. Click the pencil icon (✏️) near the top-right of the file content

    Screenshot: File view with pencil/edit icon highlighted

  4. The file opens in an editor. Make your changes.

    Your documentation uses Markdown — a simple way to format text. For example: **bold** becomes bold, # Heading becomes a large heading. See the Markdown guide below for more.

    Screenshot: GitHub file editor with some text being typed

4.1 Learn how to edit Markdown files with pretty customization

  1. When you're done editing, scroll down to the Commit changes section

  2. Optionally, write a short note describing what you changed (e.g. "Update introduction")

  3. Click Commit changes

    Screenshot: Commit changes form with green Commit button highlighted

  4. Go back to your Docsbook site and refresh — your changes appear immediately.

Add a new page#

  1. Go to your repository on GitHub

  2. Click Add file → Create new file

    Screenshot: Add file dropdown with "Create new file" option highlighted

  3. In the Name your file field, type the path and filename. For example: guides/installation.md

    Typing a / in the name automatically creates a folder. For example, guides/installation.md creates a guides folder with installation.md inside.

    Screenshot: New file name field with "guides/installation.md" typed

  4. Write your content in the editor below

  5. Click Commit new file

    Screenshot: Commit new file button highlighted

The new page appears in your Docsbook sidebar automatically.

Delete a page#

  1. Open the file in your repository

  2. Click the ⋯ (three dots) menu icon near the top-right

    Screenshot: File view with three-dot menu highlighted

  3. Click Delete file

  4. Click Commit changes to confirm

Option B — Edit with Claude Code (AI-assisted, no terminal needed)#

Claude Code — это AI-помощник по программированию, который может читать, создавать и редактировать ваши файлы документации посредством диалога — без необходимости использования командной строки или знаний Git. Отлично подходит, если вам нужно быстро создать много контента.

Setup (one time)#

  1. Перейдите по адресу claude.ai/code и скачайте Claude Code

  2. Установите его, следуя инструкциям на экране

  3. Откройте Claude Code и скажите:

    "Клонируйте мой репозиторий GitHub github.com/YOUR-USERNAME/YOUR-REPO-NAME на мой компьютер и откройте его"

    Claude выполнит все остальное — без необходимости использования командной строки.

Creating and editing documentation#

Просто опишите, что вы хотите, в панели чата:

Создать новую страницу

"Создайте новый файл с именем guides/installation.md с руководством для начинающих. Включите разделы о системных требованиях, шагах установки и первом входе в систему."

Редактировать существующую страницу

"Откройте guides/quick-start.md и добавьте раздел «Устранение неполадок» в конце с 5 распространенными проблемами и решениями."

Переписать или улучшить

"Прочитайте guides/quick-start.md и сделайте его короче и проще — ориентируйтесь на человека без технического образования."

Создать несколько страниц одновременно

"Создайте следующие страницы: guides/faq.md с 10 вопросами о выставлении счетов и api/overview.md с обзором REST API."

Claude пишет контент и сохраняет файлы. Просмотрите результат и запросите корректировки, если это необходимо.

Screenshot: Claude Code chat with a request typed and the response being written into the file

Save and publish your changes#

Когда вы закончите, просто скажите Claude:

"Зафиксировать все изменения и отправить в GitHub."

Claude выполнит необходимые команды для вас. Ваш сайт Docsbook обновится в считанные секунды.

Подключите ваши документы#

Затем вам следует подключить репозиторий, перейдите по ссылке docsbook.io/connect — эта страница позволяет войти в систему с помощью GitHub и выбрать репозиторий в любое время.

Основы Markdown#

Docsbook использует Markdown — простой набор символов, которые управляют тем, как форматируется текст. Вот все, что вам нужно знать:

Текстовое форматирование#

Что вы вводите Как это выглядит
**bold text** жирный текст
*italic text* курсивный текст
~~strikethrough~~ зачеркнутый
`inline code` inline code

Заголовки#

# Large heading (page title)
## Medium heading (section)
### Small heading (sub-section)

Списки#

- First item
- Second item
  - Nested item (indent with 2 spaces)
 
1. First step
2. Second step
3. Third step
[Click here](https://example.com)
[Link to another page in your docs](/ru/docs/guides/getting-started/other-page)

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

![Description of image](https://raw.githubusercontent.com/docsbook-io/docs/main/guides/getting-started/./images/my-screenshot.png)

Блоки кода#

Используйте тройные обратные кавычки, чтобы отображать код с подсветкой синтаксиса:

```javascript
console.log("Hello!")
```

Callout / Quote#

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

Docsbook автоматически создает боковую навигацию на основе структуры ваших файлов и папок. Настраивать ничего не нужно.

Файлы в вашем репозитории Боковая панель в Docsbook
README.md Главная
installation.md Установка
guides/quick-start.md Руководства → Быстрый старт
api/overview.md Api → Обзор

Советы:

  • Имена файлов и папок становятся заголовками страниц (дефисы заменяются на пробелы)
  • README.md внутри папки становится главной страницей для этой папки
  • Имена в нижнем регистре с дефисами лучше всего подходят для URL: getting-started.md → /getting-started

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

Работает на Docsbook