Zimin A.N.
d5268b9395
Новая документация-as-code на платформе Diplodoc (Yandex open-source) с YFM (Yandex Flavored Markdown). Build → static HTML, deployable куда угодно. Что добавлено: - package.json + .yfm + toc.yaml — Diplodoc setup, навигация для sidebar - index.md — главная страница с tabs для разных audiences - README.md — инструкция для contributors Раздел integration/api/ — 11 страниц про интеграцию consumers: - index — обзор + глоссарий - auth — Keycloak service accounts, scope mapping - read-endpoints — GET /dictionaries, list/by-key, spatial filters - events — Kafka outbox топики, partition keys, idempotency, DLQ - webhooks — HMAC, SSRF guard, retry policy, test ping endpoint - bitemporal — validFrom/validTo + history, future-dated entries, bulk close/export - x-references — FK syntax, validation errors, scope hiding, orphan scanner, v2 cascade preview - caching — TTL / push / snapshot strategies, hybrid pattern - errors — full error code reference (validation/auth/conflict/server), retry strategy - best-practices — 33 numbered rules для consumers - bundle-cuod — все 40 справочников с FK графом и сценариями Обновлены: - ops/README.md — link на новую integration/api/, убран inline <br> - ops/slo.md — broken cross-repo links заменены на text references Build: cd docs && pnpm install && pnpm build → ./_dist (20 HTML files, 7.1M) pnpm serve # → http://localhost:8088 CI deploy job для GitLab Pages — в roadmap (см. docs/README.md). Существующий tech/api-integration.md оставлен в toc как legacy (содержимое мигрировано + расширено в integration/api/).
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+.
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:
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 %}— выделенные блокиmermaidcode 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