Документы

Пишите документацию, ранбуки и ADR рядом с досками: живые диаграммы, комментарии, история версий и синхронизация из git.

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

#Как создать документ

На странице проекта нажмите «Создать» и выберите:

• «Документ» — пустая страница. Пока она пустая, можно начать с шаблона.
• «Документ из Markdown…» — загрузить файл .md.
• «Импорт из Notion или Confluence…» — перенести существующие страницы (подробнее ниже).
• «Документы из git…» — публиковать папку репозитория из CI (подробнее ниже).

#Шаблоны

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

Редактор понимает Markdown прямо во время набора: #, ## и ### — заголовки, - — маркированный список, 1. — нумерованный, [ ] — список задач, > — цитата, три обратные кавычки — блок кода, --- — разделитель.

Нажмите / на пустой строке, чтобы открыть меню блоков: текст, заголовки, списки, список задач, выноски, раскрывающийся блок, цитата, код, диаграмма из кода, диаграмма с доски, таблица, картинка и разделитель. Если выделить текст, появится панель форматирования: жирный, курсив, зачёркнутый, код в строке, ссылка и «Комментарий».

• Выноски бывают пяти видов: «Заметка», «Совет», «Важно», «Внимание» и «Опасно». В Markdown они записываются как на GitHub, пример ниже.
• Раскрывающиеся блоки сворачиваются и разворачиваются. В Markdown это <details> с заголовком в <summary>.
• Блоки кода подсвечивают синтаксис Bash, YAML, JSON, TypeScript, Python, Go, SQL и других языков.
• Таблицы умеют добавлять строки и столбцы, включать строку заголовков и удалять строки, столбцы или всю таблицу.
• Картинки можно вставить из буфера, перетащить или добавить через меню /. Они загружаются в документ.

> [!WARNING]
> Перед перезапуском выведите ноду из работы.

<details>
<summary>Как откатить</summary>

1. Откатите релиз.
2. Проверьте дашборды.

</details>

Если вставленный Markdown остался обычным текстом, выделите его и нажмите «Оформить как Markdown». По длинному документу удобно перемещаться через «Содержание», которое строится из заголовков.

#Диаграммы в документах

Диаграмму в документ можно добавить двумя способами.

Диаграмма из кода. Вставьте «Диаграмму из кода» через меню / или блок кода с языком «Mermaid (диаграмма)». Напишите код на Mermaid или D2, и под ним появится схема. Когда закончите, код можно скрыть. «Скопировать на новую доску» превращает схему в фигуры на доске, которые можно редактировать.

Живая диаграмма с доски. Она следит за доской: когда кто-то меняет диаграмму там, документ показывает новую версию.

1. На доске выделите диаграмму и нажмите «Скопировать ссылку для документа».
2. В документе вставьте ссылку на пустую строку.

Можно и через меню /: выберите «Диаграмма с доски», затем доску и одну из её диаграмм или «Вся доска». В Markdown живая диаграмма — это блок doska:

```doska
board: <id доски>
diagram: <id диаграммы>
```

Без строки diagram: показывается вся доска. В меню блока есть «Открыть доску», «Показать другую диаграмму…» и «Отвязать: оставить копию кода».

#Комментарии

Выделите текст и нажмите «Комментарий». Через @ можно упомянуть коллегу, ему придёт уведомление. Обсуждения собраны сбоку от документа, решённые уходят на отдельную вкладку. Если текст, к которому был комментарий, удалят, комментарий останется с пометкой об этом.

#Иконки и обратные ссылки

Наведите курсор на заголовок и нажмите «Добавить иконку», чтобы выбрать эмодзи для документа.

Вставленная ссылка на другую доску или документ превращается в ссылку с названием этой страницы. Внизу каждого документа блок «Упоминается в» показывает документы, которые на него ссылаются или показывают его диаграммы.

#История версий

Пока документ правят, Doska сама сохраняет версию каждые полчаса, а важные моменты можно сохранить вручную. Откройте «Историю версий» в верхней панели, чтобы посмотреть старую версию и восстановить её. Восстановление заменяет документ у всех участников, а текущее состояние перед этим сохраняется в истории.

В меню документа можно выгрузить «Файл Markdown (.md)», «Скопировать как Markdown», «Создать копию» или «Заменить файлом Markdown…» (текущий текст останется в истории).

#Документы из git

Храните документацию в репозитории и публикуйте её в Doska после каждого merge. Каждый Markdown-файл папки становится документом, подпапки — папками, а относительные ссылки между файлами продолжают работать.

1. В проекте выберите «Создать» → «Документы из git…» и создайте токен доступа с правом редактирования этого проекта.
2. Сохраните токен в репозитории как секрет DOSKA_TOKEN.
3. Добавьте workflow из окна как .github/workflows/doska-docs.yml. Он выглядит так:

name: Docs to Doska
on:
  push:
    branches: [main]
    paths: ['docs/**']
  workflow_dispatch:
jobs:
  doska:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - run: |
          curl -fsSL https://getdoska.top/docs-sync.mjs -o /tmp/docs-sync.mjs
          node /tmp/docs-sync.mjs --project <id проекта> --dir docs
        env:
          DOSKA_TOKEN: ${{ secrets.DOSKA_TOKEN }}

4. Сделайте push в main.

Скрипту нужен только Node 18+, без зависимостей, поэтому он работает в любом CI. Параметры: --dir — другая папка, --folder "Docs" — положить документы в папку проекта, --prune — удалять документы, чьи файлы удалены. Название документа берётся из title: во front matter, иначе из первого заголовка #, иначе из имени файла. Неизменённые файлы не трогаются, у изменённых прошлый текст остаётся в истории версий.

У синхронизированных документов есть пометка «Из git» со ссылкой на файл. Правьте их в репозитории: изменения, сделанные в Doska, заменятся при следующей синхронизации. Эндпоинт, который вызывает скрипт, описан в справочнике API.

#Импорт из Notion и Confluence

1. Выгрузите содержимое:
   • Notion: Export → «Markdown & CSV», получится .zip.
   • Confluence: настройки пространства → Экспорт → HTML.
2. В проекте выберите «Создать» → «Импорт из Notion или Confluence…» и укажите .zip (подойдут и отдельные файлы .md или .html).
3. Выберите папку в проекте и импортируйте.

Страницы станут документами, вложенность — папками, а ссылки между страницами продолжат работать. Картинки пока не переносятся.