TinaDocs — Руководство по установке и использованию

Версия: 1.0
Дата: 19.04.2026
Статус: Утверждён

Полное руководство по развёртыванию документационной системы на базе TinaDocs (Next.js + TinaCMS) с Git-хранилищем, визуальным редактором и деплоем на VPS.

Цель и концепция

TinaDocs — это готовая платформа для документации на базе Next.js 15 + TinaCMS. Цель та же что и у Docusaurus + Decap CMS: единый Git-репозиторий как источник правды, редактирование через браузер, публикация через сборку.

content/docs/ (MDX файлы)
  └── Git репозиторий  ← единственный источник правды
        ├── Next.js     → статический сайт / Node.js сервер
        └── TinaCMS     → браузерная админка /admin

Принцип работы:

Все документы — MDX файлы в папке content/docs/
Git хранит всю историю изменений
TinaCMS редактирует файлы через браузер с визуальным предпросмотром в реальном времени
Next.js компилирует MDX и строит сайт

Сравнение с Docusaurus + Decap CMS

Критерий	Docusaurus + Decap CMS	TinaDocs + TinaCMS
Редактор	Markdown тулбар (базовый)	Визуальный WYSIWYG с живым предпросмотром
Синхронный скролл	Нет	Да — редактор и предпросмотр синхронизированы
Формат файлов	`.md`	`.mdx` (обязательно)
Встроенные компоненты	Нет	Accordion, Callout, Code Tabs, Card Grid, API Reference, YouTube, и др.
Поиск	Нет (нужен плагин)	Встроенный Pagefind
Темы оформления	Минимальные	6 готовых тем: Default, Tina, Blossom, Lake, Pine, Indigo
API документация	Нет	Встроенная загрузка OpenAPI/Swagger
Черновики	`draft: true` в frontmatter	`draft: true` в frontmatter
Сложность установки	Проще	Сложнее (TinaCloud для prod или самохостинг)
Деплой без Node.js	Да (чистый HTML)	Только при `npm run export` (static mode)
Деплой на VPS	Не нужен Node.js	Node.js обязателен для TinaCMS admin
Защита паролем	`.htaccess` (shared)	Middleware Next.js или nginx (VPS)
Стоимость	Бесплатно	Бесплатно при самохостинге TinaCMS

Когда выбирать TinaDocs:

Нужен удобный визуальный редактор с живым предпросмотром
Нужны встроенные компоненты (callout, accordion, api reference)
Есть VPS или Vercel для деплоя
Документы сложнее простого Markdown

Когда выбирать Docusaurus + Decap:

Нужен простой деплой на shared хостинг (чистый HTML, FTP)
Достаточно базового MD редактора
Минимальные требования к серверу

Преимущества TinaDocs

Визуальный редактор — видишь результат прямо в процессе редактирования, синхронный скролл работает
Богатые компоненты — вставка accordion, callout, code tabs, youtube, api reference прямо из UI без ручного написания MDX
Встроенный поиск — Pagefind индексирует весь контент без внешних сервисов
API документация — загрузка OpenAPI/Swagger файлов и автогенерация страниц
6 тем — смена оформления без правки кода
GitHub интеграция — отображение "последний редактор" и дата изменения
Самохостинг TinaCMS — без зависимости от облака если развернуть на VPS

Недостатки TinaDocs

Только MDX — файлы .md не индексируются, только .mdx
Требует Node.js на сервере — для работы CMS admin нельзя просто залить HTML
Сложнее в настройке — больше переменных окружения, нужен TinaCloud или самохостинг
Тяжелее — Next.js + TinaCMS + Monaco Editor > Docusaurus + Decap
TinaCloud — облачный сервис для prod (бесплатный тариф есть, но есть лимиты)

Требования

Node.js v20+ (проверить: node --version)
pnpm (npm install -g pnpm) — рекомендуется, npm тоже работает
Git
WSL если на Windows (проект должен лежать на Linux FS, не на NTFS)

Для деплоя на VPS:

Ubuntu 22.04 / Debian 12
Node.js v20+ на сервере
PM2 (npm install -g pm2) для запуска как сервиса
nginx для проксирования и SSL

Установка с нуля

1. Клонировать или создать проект

Если разворачиваешь с нуля (шаблон):

npx create-tina-app@latest tina-docs
cd tina-docs
pnpm install

Если разворачиваешь из существующего репозитория:

git clone <url или путь к bundle> tina-docs
cd tina-docs
pnpm install

2. Создать файл .env.local

cp .env.example .env.local

Для локальной работы без TinaCloud достаточно пустого файла — TinaCMS работает в local mode. Оставь переменные пустыми или закомментированными:

# Для локальной работы — оставь пустым
NEXT_PUBLIC_TINA_CLIENT_ID=
TINA_TOKEN=
NEXT_PUBLIC_TINA_BRANCH=
NEXT_PUBLIC_SITE_URL=http://localhost:3000

3. Переименовать ветку в main

git branch -m master main

TinaCMS по умолчанию работает с веткой main.

4. Запустить dev сервер

pnpm dev

После запуска:

Сайт: http://localhost:3000
Админка CMS: http://localhost:3000/admin

Структура папок

tina-docs/
  content/
    docs/                   ← сюда кладёшь MDX файлы документов
      index.mdx             ← главная страница документации
      introduction/
        getting-started.mdx
    apiSchema/              ← OpenAPI/Swagger JSON файлы
    navigation-bar/         ← конфигурация навигации
    settings/               ← глобальные настройки
  tina/
    collections/
      docs.tsx              ← схема коллекции документов
      navigation-bar.tsx    ← схема навигации
    templates/
      markdown-embeds/      ← компоненты вставки (callout, accordion и др.)
    config.ts               ← основной конфиг TinaCMS
    schema.tsx              ← схема данных
    __generated__/          ← автогенерация (не редактировать)
  src/
    app/                    ← Next.js App Router страницы
    components/             ← React компоненты
  public/
    admin/                  ← сборка CMS admin (генерируется)
    img/                    ← картинки
    diagrams/               ← SVG диаграммы
  .env.local                ← переменные окружения (не в git)
  .env.example              ← шаблон переменных
  next.config.js
  tina/config.ts
  package.json

Документы: правила и ограничения

Формат файлов — только MDX

TinaDocs индексирует только файлы .mdx. Файлы .md игнорируются CMS и не появляются в списке документов.

# Переименовать все .md в .mdx если нужно
find content/docs -name "*.md" | while read f; do mv "$f" "${f%.md}.mdx"; done

Frontmatter (обязателен)

---
title: "Название документа"
---

# Название документа
...

Черновики

---
title: "Черновик"
draft: true
---

Черновики (draft: true) не попадают в продакшн сборку — поведение аналогично Docusaurus.

Через CMS: открой документ → поле Draft → включи → сохрани.

Картинки

Картинки кладутся в public/:

public/img/screenshot.jpg
public/diagrams/schema.jpg

Вставка в MDX:

![Описание](/img/screenshot.jpg)

Путь начинается с / — абсолютный от корня сайта.

Встроенные компоненты (embeds)

В редакторе CMS можно вставлять блоки через кнопку +:

Callout — информационный блок (note, warning, tip)
Accordion — раскрывающийся блок вопрос/ответ
Code Tabs — вкладки с кодом на разных языках
Card Grid — сетка карточек
API Reference — блок описания API метода
YouTube — встроенное видео
File Structure — дерево файлов

В MDX они выглядят как JSX компоненты — не трогай их вручную если не знаешь синтаксис.

Запуск для разработки

cd /home/alex/sites/tina-docs
pnpm dev

Сайт: http://localhost:3000
Админка: http://localhost:3000/admin

В dev режиме TinaCMS работает в local mode — сохраняет изменения напрямую в файлы и делает git commit автоматически. TinaCloud не нужен.

Показ документов другим людям (локально)

Аналог serve_preview.sh из Docusaurus комплекта:

cd /home/alex/sites/tina-docs
pnpm build
pnpm start

Или статический экспорт (без Node.js на стороне показа):

pnpm export
# Папка .next/static/ содержит статику
# Но: /admin (CMS) в static режиме не работает

Твой dev: http://localhost:3000 (с черновиками)
Для людей: http://localhost:3000 после pnpm start (без черновиков)

Деплой на VPS

Требования к серверу

Ubuntu 22.04 / Debian 12
Node.js v20+ (curl -fsSL https://deb.nodesource.com/setup_20.x | sudo bash - && sudo apt install nodejs)
pnpm (npm install -g pnpm)
PM2 (npm install -g pm2)
nginx
Certbot для SSL (Let's Encrypt)

Шаги деплоя

1. Скопировать проект на сервер

# С локальной машины через git bundle
git bundle create tina-docs.bundle main
scp tina-docs.bundle user@server:/home/user/

# На сервере
git clone tina-docs.bundle tina-docs
cd tina-docs
pnpm install

2. Создать .env.local на сервере

nano .env.local

NEXT_PUBLIC_SITE_URL=https://docs.yourdomain.com
NEXT_PUBLIC_TINA_BRANCH=main

# Для работы CMS admin на сервере — нужен TinaCloud или self-hosted
# (см. раздел TinaCloud ниже)
NEXT_PUBLIC_TINA_CLIENT_ID=your_client_id
TINA_TOKEN=your_token

3. Собрать и запустить через PM2

pnpm build
pm2 start "pnpm start" --name tina-docs
pm2 save
pm2 startup  # автозапуск при перезагрузке сервера

Проверить статус:

pm2 status
pm2 logs tina-docs

4. Настроить nginx

server {
    listen 80;
    server_name docs.yourdomain.com;

    location / {
        proxy_pass http://localhost:3000;
        proxy_http_version 1.1;
        proxy_set_header Upgrade $http_upgrade;
        proxy_set_header Connection 'upgrade';
        proxy_set_header Host $host;
        proxy_cache_bypass $http_upgrade;
    }
}

sudo ln -s /etc/nginx/sites-available/tina-docs /etc/nginx/sites-enabled/
sudo nginx -t
sudo systemctl reload nginx

5. SSL через Let's Encrypt

sudo apt install certbot python3-certbot-nginx
sudo certbot --nginx -d docs.yourdomain.com

Certbot сам обновит nginx конфиг для HTTPS.

Защита паролем на VPS (nginx)

Защита через nginx basic auth — без зависимости от приложения.

Шаг 1. Установить apache2-utils:

sudo apt install apache2-utils

Шаг 2. Создать файл паролей:

sudo htpasswd -c /etc/nginx/.htpasswd admin
# Введи пароль при запросе

Добавить ещё пользователя (без -c — не перезаписывает файл):

sudo htpasswd /etc/nginx/.htpasswd editor

Шаг 3. Добавить в nginx конфиг:

server {
    listen 443 ssl;
    server_name docs.yourdomain.com;

    # SSL настройки (добавит certbot)

    location / {
        auth_basic "Документация";
        auth_basic_user_file /etc/nginx/.htpasswd;

        proxy_pass http://localhost:3000;
        proxy_http_version 1.1;
        proxy_set_header Host $host;
    }

    # Исключить /admin из парольной защиты если нужен отдельный доступ
    # или наоборот — защитить только /admin
}

Шаг 4. Перезагрузить nginx:

sudo nginx -t && sudo systemctl reload nginx

Проверка: открой https://docs.yourdomain.com — браузер запросит логин и пароль.

TinaCloud — для работы CMS admin в продакшне

Без TinaCloud CMS admin (/admin) работает только в local mode (localhost). На сервере без TinaCloud admin недоступен.

Бесплатный тариф TinaCloud: до 2 пользователей, неограниченный контент.

Настройка:

Зайти на app.tina.io
Создать проект → подключить GitHub репозиторий
Скопировать Client ID и Token

Добавить в .env.local на сервере:

NEXT_PUBLIC_TINA_CLIENT_ID=xxxxx
TINA_TOKEN=xxxxx
NEXT_PUBLIC_TINA_BRANCH=main

Пересобрать: pnpm build && pm2 restart tina-docs

После этого /admin на сервере работает и сохраняет изменения через GitHub API (не напрямую в файлы).

Поток сохранения через TinaCloud:

CMS admin → TinaCloud → GitHub commit → сервер pull → pnpm build → перезапуск

Для автоматического деплоя при push — настрой webhook или CI/CD (GitHub Actions).

Обновление сайта после правок

Если работаешь локально и деплоишь на VPS вручную

# Локально — собери бандл и перенеси на сервер
git bundle create update.bundle main
scp update.bundle user@server:/home/user/tina-docs/

# На сервере
cd /home/user/tina-docs
git fetch /home/user/update.bundle main:main
git merge main
pnpm install
pnpm build
pm2 restart tina-docs

Если используешь TinaCloud + GitHub

Редактируешь в /admin → TinaCloud пушит коммит в GitHub → настрой GitHub Actions для автодеплоя.

Связь с Git

Действие	Что происходит в Git
Сохранить в CMS (local mode)	Автоматический коммит в текущую ветку
Сохранить в CMS (TinaCloud)	Коммит через GitHub API
Положить файл в `content/docs/` вручную	Нужно сделать `git add` + `git commit`
Включить черновик	Коммит с `draft: true` в frontmatter

Частые проблемы

CMS не видит документы

Файлы имеют расширение .md вместо .mdx. TinaDocs индексирует только .mdx.

find content/docs -name "*.md" | while read f; do mv "$f" "${f%.md}.mdx"; done

"Unable to find record" в CMS

Тот же симптом — неправильное расширение файла. Переименуй в .mdx.

Ошибка сборки — компонент не найден

Проверь что MDX файл не содержит JSX компоненты которых нет в проекте. Компоненты вставляются только через CMS или должны быть зарегистрированы в tina/templates/.

pm2 не запускается после перезагрузки сервера

pm2 startup  # выполни команду которую он выведет
pm2 save

Поиск не работает

Pagefind индекс строится во время pnpm build. Если запускаешь dev сервер — поиск не работает, только в продакшн сборке.

CMS admin недоступен на сервере (белый экран или ошибка)

Не настроен TinaCloud. На VPS без TinaCloud CMS работает только локально. Настрой NEXT_PUBLIC_TINA_CLIENT_ID и TINA_TOKEN.

Цель и концепция​

Сравнение с Docusaurus + Decap CMS​

Преимущества TinaDocs​

Недостатки TinaDocs​

Требования​

Установка с нуля​

Структура папок​

Документы: правила и ограничения​

Формат файлов — только MDX​

Frontmatter (обязателен)​

Черновики​

Картинки​

Встроенные компоненты (embeds)​

Запуск для разработки​

Показ документов другим людям (локально)​

Деплой на VPS​

Требования к серверу​

Шаги деплоя​

Защита паролем на VPS (nginx)​

TinaCloud — для работы CMS admin в продакшне​

Обновление сайта после правок​

Если работаешь локально и деплоишь на VPS вручную​

Если используешь TinaCloud + GitHub​

Связь с Git​

Частые проблемы​