Markdown для документации

Какие таблицы нужны в документации

Техническая документация без таблиц — стена текста. С таблицами — структурированная информация, которую разработчик находит за секунды. Хорошая API-документация на 30-40% состоит из таблиц: endpoints, параметры, коды ошибок, опции конфигурации.

Markdown — стандарт для технической документации (MDN, GitHub Pages, MkDocs, Docusaurus, Read the Docs). Таблицы в MD легко читаются в исходнике, отлично рендерятся в любом инструменте, версионируются в git.

Готовые паттерны

1. API endpoints

| Method | Endpoint | Description | Auth |
| :----: | :------- | :---------- | :--: |
| GET | /api/users | Список всех пользователей | ✓ |
| GET | /api/users/:id | Один пользователь | ✓ |
| POST | /api/users | Создать пользователя | ✓ admin |
| PUT | /api/users/:id | Обновить | ✓ owner |
| DELETE | /api/users/:id | Удалить | ✓ admin |

2. Параметры функции

### fetch(url, options)

| Параметр | Тип | Default | Описание |
| :------- | :-- | :-----: | :------- |
| url | string | — | URL запроса (обязательно) |
| options.method | string | "GET" | HTTP метод |
| options.headers | Record<string, string> | {} | Заголовки запроса |
| options.body | string \| FormData | undefined | Тело запроса |
| options.timeout | number | 30000 | Таймаут в мс |
| options.retry | number | 0 | Количество повторов |

3. HTTP коды ответов

### Возможные ответы

| Код | Значение | Когда возвращается |
| :-: | :------- | :----------------- |
| 200 | OK | Успешный запрос |
| 201 | Created | Создан новый ресурс |
| 400 | Bad Request | Невалидные параметры |
| 401 | Unauthorized | Нет токена / просрочен |
| 403 | Forbidden | Нет прав на ресурс |
| 404 | Not Found | Ресурс не существует |
| 409 | Conflict | Email уже занят |
| 429 | Too Many Requests | Rate limit |
| 500 | Internal Server Error | Bug в API |

4. Compatibility matrix

### Browser support

| Feature | Chrome | Firefox | Safari | Edge | Opera |
| :------ | :----: | :-----: | :----: | :--: | :---: |
| WebGPU | ✅ 113+ | ⚠️ Behind flag | ⚠️ TP | ✅ 113+ | ✅ 99+ |
| WebRTC | ✅ | ✅ | ⚠️ Limited | ✅ | ✅ |
| WebAssembly | ✅ | ✅ | ✅ | ✅ | ✅ |
| Service Worker | ✅ | ✅ | ✅ | ✅ | ✅ |
| Web Bluetooth | ✅ | ❌ | ❌ | ✅ | ✅ |

**Легенда:** ✅ полная поддержка · ⚠️ частичная · ❌ не поддерживается

5. Configuration options

### Опции config.json

| Ключ | Тип | Default | Required | Описание |
| :--- | :-- | :-----: | :------: | :------- |
| port | number | 3000 | — | Порт сервера |
| host | string | "0.0.0.0" | — | Адрес bind |
| logLevel | "debug" \| "info" \| "warn" \| "error" | "info" | — | Уровень логирования |
| db.url | string | — | ✓ | Connection string |
| db.poolSize | number | 10 | — | Размер пула |
| auth.jwtSecret | string | — | ✓ | Секрет для JWT |
| auth.jwtExpiresIn | string | "15m" | — | TTL access token |

6. Сравнение с конкурентами

### Сравнение с альтернативами

| Возможность | Наш продукт | Конкурент A | Конкурент B |
| :---------- | :---------: | :---------: | :---------: |
| Открытый код | ✅ MIT | ❌ Proprietary | ✅ Apache |
| Бесплатный план | ✅ Forever | ⚠️ Trial 14д | ✅ Limited |
| TypeScript first-class | ✅ | ⚠️ d.ts only | ❌ |
| Self-hosted | ✅ | ❌ Cloud only | ✅ |
| GraphQL API | ✅ | ❌ REST only | ❌ |
| Цена (Pro) | $9/mo | $29/mo | $19/mo |

Хорошая техническая документация состоит из 4 типов: tutorials (учим делать что-то), how-to guides (решаем конкретные задачи), reference (справочник), explanation (концепции). Таблицы — основа reference-документации.— Diátaxis Framework — A systematic approach to technical documentation

Инструменты для документации

MkDocs (Python)

• Простой статический сайт из MD файлов.
• Тема Material for MkDocs — лучшая визуально.
• Sortable таблицы через плагин mkdocs-table-reader-plugin.
• Интеграция с Read the Docs.
• Использует Python — нужен pip и virtualenv.

Docusaurus (React)

• От Facebook, использует React + MDX.
• Версионирование документации (v1, v2, v3).
• Локализация (i18n) встроенная.
• React-компоненты внутри MD (через MDX).
• Лучший выбор для open source проектов.

VitePress (Vue)

• Альтернатива от Vue экосистемы.
• Очень быстрая сборка через Vite.
• Минималистичный, лёгкий.
• Использует Vitest 3 для тестов в документации.

Read the Docs + Sphinx

• Стандарт для Python-документации.
• RST или Markdown через myst-parser.
• Автоматическая сборка и хостинг через ReadTheDocs.io.
• Многоверсионная документация.

Автогенерация таблиц

TypeDoc для TypeScript

/**
 * Делает HTTP запрос с retry.
 *
 * @param url - URL для запроса
 * @param options - Опции запроса
 * @param options.timeout - Таймаут в мс (default: 5000)
 * @param options.retry - Количество повторов (default: 0)
 * @returns Promise с ответом
 */
export function fetch(url: string, options?: FetchOptions): Promise<Response>;

// TypeDoc автоматически сгенерирует MD таблицу
// параметров и опций из этих JSDoc-комментариев

swagger2markdown

# Из OpenAPI 3.0 spec в Markdown
npm install -g swagger2markdown
swagger2markdown -i swagger.yaml -o api.md

# Результат — MD файл с таблицами всех endpoints

Pre-commit hook для синхронизации

# .husky/pre-commit
#!/bin/sh

# Регенерировать API docs при изменении кода
if git diff --cached --name-only | grep -q "src/"; then
  npm run docs:generate
  git add docs/api.md
fi

Best practices

• Single source of truth. Если возможно — генерируйте таблицы из кода (JSDoc, OpenAPI). Иначе они устаревают.
• Версионирование. Документация в одном репо с кодом — синхронизация через git. Изменения видны в PR review.
• Examples в каждой таблице. После таблицы параметров — пример использования. Пользователь часто читает примеры, а не таблицы.
• Не больше 7 колонок. Иначе не помещается на мобильный экран. Если нужно — разделите на 2 таблицы.
• Sortable таблицы для длинных списков. Если 50+ строк — нужна сортировка (плагины MkDocs, Docusaurus).
• Searchable docs. Алгоблия / Lunr.js для поиска по всей документации. Tables индексируются как обычный текст.