# Ordinis docs (Diplodoc / YFM)

Документация Ordinis НСИ ЦУОД ОДХ построена через **Diplodoc** (open-source
documentation platform от Yandex). Markdown source — YFM (Yandex Flavored
Markdown) с расширениями для tabs, notes, includes, mermaid диаграмм.

## Структура

```
docs/
├── package.json           # @diplodoc/cli + scripts
├── .yfm                   # Diplodoc config (langs, plugins)
├── toc.yaml               # Содержание / навигация (рендерится в sidebar)
├── index.md               # Главная страница
├── integration/           # Интеграция по API
│   ├── api/               # Главы для consumers
│   │   ├── index.md       # Обзор
│   │   ├── auth.md        # Keycloak / JWT
│   │   ├── read-endpoints.md
│   │   ├── events.md      # Kafka outbox
│   │   ├── webhooks.md
│   │   ├── bitemporal.md
│   │   ├── x-references.md
│   │   ├── caching.md
│   │   ├── errors.md
│   │   ├── best-practices.md
│   │   └── bundle-cuod.md
│   └── altum-imaging-order.md   # Прикладной сценарий
├── ops/                   # Operator runbook
│   ├── README.md
│   ├── slo.md
│   ├── outbox-dlq.md
│   ├── db-migrations.md
│   ├── vault-unseal.md
│   └── kafka-restart.md
├── status/                # State snapshots (исключено из build)
│   └── *-state.md
└── tech/                  # Legacy технические страницы
    └── api-integration.md
```

## Сборка

Требуется Node 18+.

```bash
cd docs
pnpm install
pnpm build           # → ./_dist (HTML)
pnpm serve           # → http://localhost:8088
# либо одной командой:
pnpm dev
```

Build output (`_dist/`) — статический HTML, можно деплоить в:
- GitLab Pages
- S3 + CloudFront
- nginx/ingress на cluster.142

## Автор содержимого

| Раздел | Owner |
|---|---|
| `/` (index, integration/api/*) | zimin.an@nstart.space |
| `ops/*` | on-call rotation team |
| `integration/altum-imaging-order.md` | Альтум team contact |

## Что не committable

- `_dist/` — build output (gitignore'нут)
- `node_modules/` — dependencies (gitignore'нут)

## Deployment

В roadmap — GitLab CI job `build-docs`:

```yaml
build-docs:
  stage: build
  image: node:18
  script:
    - cd docs
    - pnpm install --frozen-lockfile
    - pnpm build
  artifacts:
    paths: [docs/_dist]
    expire_in: 1 week
  rules:
    - changes: ["docs/**/*"]
```

Затем deploy в GitLab Pages либо как отдельный k8s deployment с nginx.

## YFM extensions используются

- `{% list tabs %}` — табы для switching между audiences
- `{% note info|warning|tip %}` — выделенные блоки
- `mermaid` code blocks — диаграммы (graph LR, gantt)
- Cross-links в `toc.yaml` — sidebar navigation
- `varsPreset: external` — для shared includes (TBD when нужно)

## Roadmap

- [ ] CI job `build-docs` в `.gitlab-ci.yml`
- [ ] GitLab Pages deployment
- [ ] Search через Diplodoc search plugin
- [ ] EN translation (i18n via `langs:` в `.yfm`)
- [ ] Includes для shared snippets (auth examples, error tables)
- [ ] Versioning — separate doc trees per Ordinis major version