docs: add svg-sized, svg-inline, svg-object variants

Three more ways to embed standalone.svg in markdown:

- svg-sized.md: <img> with explicit width="1200" (sanitized style attr doesn't pass)
- svg-inline.md: full SVG inline in <details> — zoomable in preview but diff-unfriendly
- svg-object.md: <object data="..."> — TESTED via /api/v1/markdown, gitea 1.27
  sanitizes it out. Kept for comparison; doesn't work in our gitea UI.
This commit is contained in:
hermes
2026-08-27 12:08:33 +00:00
parent 7dab6c89ad
commit e8fa7e8be4
3 changed files with 211 additions and 0 deletions
+119
View File
@@ -0,0 +1,119 @@
# Production architecture (inline SVG variant)
> **Вариант №6:** SVG **целиком inline** в markdown, обёрнут в `<details>` чтобы md-файл
> остался читаемым. Раскрываешь — видишь интерактивный SVG с возможностью зума.
## Зачем
- SVG можно зумить в браузере (Ctrl+Scroll)
- Можно выделять элементы, copy-paste текст
- Нет зависимости от внешнего файла
<details>
<summary>📊 Click to expand inline SVG (snapshot 2026-08-27)</summary>
<svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 800 700" font-family="ui-monospace, SFMono-Regular, monospace" font-size="11">
<title>Production architecture (compact)</title>
<rect width="800" height="700" fill="#020617"/>
<!-- External -->
<rect x="20" y="20" width="160" height="160" rx="10" fill="#1e293b" fill-opacity="0.5" stroke="#94a3b8" stroke-width="1"/>
<text x="100" y="40" text-anchor="middle" fill="#94a3b8" font-size="10" font-weight="bold">EXTERNAL</text>
<ellipse cx="100" cy="80" rx="60" ry="22" fill="#1e293b" stroke="#94a3b8"/>
<text x="100" y="85" text-anchor="middle" fill="#e2e8f0" font-size="11">Client</text>
<rect x="30" y="120" width="65" height="40" rx="5" fill="#0f172a" stroke="#94a3b8"/>
<text x="62" y="140" text-anchor="middle" fill="#e2e8f0" font-size="10">Tailscale</text>
<rect x="105" y="120" width="65" height="40" rx="5" fill="#0f172a" stroke="#94a3b8"/>
<text x="137" y="140" text-anchor="middle" fill="#e2e8f0" font-size="10">Keenetic</text>
<!-- Swarm -->
<rect x="210" y="20" width="570" height="660" rx="12" fill="none" stroke="#fbbf24" stroke-dasharray="8 4"/>
<text x="495" y="40" text-anchor="middle" fill="#fbbf24" font-size="10" font-weight="bold">DOCKER SWARM CLUSTER</text>
<!-- odroid node -->
<rect x="230" y="55" width="540" height="400" rx="8" fill="none" stroke="#fbbf24"/>
<text x="500" y="75" text-anchor="middle" fill="#fef3c7" font-size="11" font-weight="bold">odroid (manager) · 192.168.1.96</text>
<!-- ingress -->
<rect x="250" y="95" width="120" height="40" rx="5" fill="#064e3b" stroke="#34d399"/>
<text x="310" y="115" text-anchor="middle" fill="#d1fae5" font-size="11" font-weight="bold">swarm ingress</text>
<text x="310" y="128" text-anchor="middle" fill="#a7f3d0" font-size="9">10.0.0.2</text>
<!-- Stack boxes -->
<g fill="#0c4a6e" stroke="#22d3ee">
<rect x="250" y="155" width="120" height="60" rx="5"/>
<rect x="385" y="155" width="120" height="60" rx="5"/>
<rect x="520" y="155" width="120" height="60" rx="5"/>
<rect x="655" y="155" width="105" height="60" rx="5"/>
<rect x="250" y="230" width="120" height="55" rx="5"/>
<rect x="385" y="230" width="120" height="55" rx="5"/>
<rect x="520" y="230" width="120" height="55" rx="5"/>
</g>
<g fill="#cffafe" text-anchor="middle" font-size="10">
<text x="310" y="175" font-weight="bold">gitea</text>
<text x="310" y="190" font-size="8">server · runner</text>
<text x="310" y="202" font-size="8">.235 / .17.13</text>
<text x="445" y="175" font-weight="bold">hermes</text>
<text x="445" y="190" font-size="8">agent · gateway</text>
<text x="445" y="202" font-size="8">.204</text>
<text x="580" y="175" font-weight="bold">hermes_infra</text>
<text x="580" y="186" font-size="8">squid · sarg</text>
<text x="580" y="196" font-size="8">docker_proxy</text>
<text x="580" y="208" font-size="8">brencher-state</text>
<text x="707" y="175" font-weight="bold">immich</text>
<text x="707" y="190" font-size="8">server · db</text>
<text x="707" y="202" font-size="8">redis · ml</text>
<text x="310" y="250" font-weight="bold">brencher</text>
<text x="310" y="265" font-size="8">.105 / .102</text>
<text x="310" y="277" font-size="8">deploys ↓</text>
<text x="445" y="250" font-weight="bold">gmail_mcp</text>
<text x="445" y="265" font-size="8">gmail · tg</text>
<text x="445" y="277" font-size="8">.6 / .10</text>
<text x="580" y="250" font-weight="bold">torrserv</text>
<text x="580" y="265" font-size="8">proxy · fs</text>
<text x="580" y="277" font-size="8">.15 / .12</text>
</g>
<!-- dead -->
<rect x="250" y="305" width="380" height="50" rx="5" fill="#1f1717" stroke="#fb7185" stroke-dasharray="6 3"/>
<text x="440" y="325" text-anchor="middle" fill="#fecaca" font-size="11" font-weight="bold">nginx_nginx (dead) · Replicas: 0</text>
<text x="440" y="340" text-anchor="middle" fill="#fecaca" font-size="9">jwilder/nginx-proxy · overlay-сеть nginx_ingress жива</text>
<text x="440" y="351" text-anchor="middle" fill="#fecaca" font-size="9">контейнеров нет</text>
<!-- xu4 worker -->
<rect x="230" y="475" width="540" height="180" rx="8" fill="none" stroke="#fbbf24"/>
<text x="500" y="495" text-anchor="middle" fill="#fef3c7" font-size="11" font-weight="bold">xu4 (worker)</text>
<rect x="320" y="525" width="360" height="50" rx="5" fill="#0f172a" stroke="#fbbf24" fill-opacity="0.5"/>
<text x="500" y="548" text-anchor="middle" fill="#fbbf24" font-size="11" font-weight="bold">worker tasks</text>
<text x="500" y="563" text-anchor="middle" fill="#94a3b8" font-size="9">(пусто в снапшоте 2026-08-27)</text>
<!-- Arrows -->
<defs>
<marker id="a" viewBox="0 0 10 10" refX="9" refY="5" markerWidth="6" markerHeight="6" orient="auto">
<path d="M 0 0 L 10 5 L 0 10 z" fill="#cbd5e1"/>
</marker>
</defs>
<line x1="170" y1="140" x2="210" y2="115" stroke="#cbd5e1" stroke-width="1.5" marker-end="url(#a)"/>
<line x1="310" y1="135" x2="310" y2="155" stroke="#cbd5e1" stroke-width="1.5" marker-end="url(#a)"/>
<line x1="310" y1="135" x2="445" y2="155" stroke="#cbd5e1" stroke-width="1" stroke-opacity="0.4" marker-end="url(#a)"/>
<line x1="310" y1="135" x2="707" y2="155" stroke="#cbd5e1" stroke-width="1" stroke-opacity="0.4" marker-end="url(#a)"/>
<line x1="310" y1="215" x2="310" y2="230" stroke="#fb7185" stroke-width="1.5" stroke-dasharray="4 3" marker-end="url(#a)"/>
<text x="40" y="700" fill="#475569" font-size="9">compact inline variant · same data as standalone.svg</text>
</svg>
</details>
## Плюсы / минусы
**+** Можно зумить, выделять элементы прямо в Gitea preview.
**+** Нет зависимости от внешнего файла (один .md — всё в нём).
**+** Спасает если SVG-файл случайно удалят.
**-** `.md` файл становится в ~2 раза длиннее.
**-** Diff нечитаемый — каждое изменение в geometry SVG ломает review.
**-** Дублирование данных: один и тот же граф в standalone.svg И в этом .md.
## Когда использовать
- Хочешь чтобы диаграмма точно была видна даже если файл `standalone.svg` случайно удалят
- Превью в PR preview без загрузки внешних ресурсов
- Когда диаграмма маленькая и diff читаемый
+45
View File
@@ -0,0 +1,45 @@
# Production architecture (`<object>` variant)
> **Вариант №7:** использует `<object data="..." type="image/svg+xml">` вместо `<img>`.
> Семантически отличается — `<object>` это embeded content, не изображение.
## Что это даёт по сравнению с `<img>`
| Свойство | `<img src="x.svg">` | `<object data="x.svg">` |
|---|---|---|
| В Gitea preview | рендерится как image | **вырезается** санитайзером (проверено через `/api/v1/markdown`) |
| Можно зумить в браузере | да | да |
| Загружает CSS внутри SVG | да | да |
| Загружает `<script>` внутри SVG | **нет** (XSS protection) | **да** (если SVG не sandboxed) |
| Fallback content | через `alt` атрибут | через `<object>...fallback...</object>` |
> **⚠️ ВАЖНО:** Gitea 1.27 вырезает `<object>` через goldmark санитайзер.
> Этот вариант **не работает** в нашем Gitea UI, но может работать в других рендерерах
> (GitHub, GitLab, Obsidian). Оставлен для сравнения.
## Диаграмма
<object data="./standalone.svg" type="image/svg+xml" width="1200" style="max-width:100%;">
Your browser does not support SVG embedding via &lt;object&gt;.
<a href="./standalone.svg">Download SVG file</a> instead.
</object>
## Плюсы / минусы
**+** Семантически правильнее для «embedded content» (SVG это не просто image, это документ).
**+** Можно использовать fallback-контент (текст, ссылка на скачивание).
**-** В Gitea preview может рендериться иначе (например, с дополнительным border/background).
**-** Если хочешь SVG-фильтры/анимации — может работать не так как `<img>`.
**-** Минимальная практическая разница для статичных диаграмм.
## Когда использовать
- Когда SVG содержит интерактивные элементы (анимация, hover)
- Когда хочешь fallback для старых браузеров
- В остальных случаях `<img>` проще и работает идентично
## Связанные
- `svg-embedded.md` — `<img>` без sizing
- `svg-sized.md` — `<img>` с sizing
- `svg-inline.md` — inline SVG в `<details>`
+47
View File
@@ -0,0 +1,47 @@
# Production architecture (sized SVG variant)
> **Вариант №5:** SVG-картинка в Markdown, но с **контролем размера** через HTML-тег `<img>`.
> Полезно если хочется ограничить максимальную ширину или принудительно растянуть.
## Чем отличается от svg-embedded.md
`svg-embedded.md` использует чистый markdown `![arch](path.svg)` — Gitea сама решает
как ресайзить. Здесь я явно указываю размеры:
```html
<img src="./standalone.svg" alt="Production architecture" width="1200" />
```
## Диаграмма (фиксированная ширина 1200px)
<img src="./standalone.svg" alt="Production architecture" width="1200" />
## Альтернативный вариант (responsive через width=100%)
```html
<img src="./standalone.svg" alt="Production architecture" width="100%" />
```
> **Примечание:** Gitea 1.27 санитизирует `style="..."` атрибуты через goldmark.
> Поэтому `style="max-width:100%; height:auto;"` **не сработает** — атрибут будет вырезан.
> Вместо этого использую `width="100%"` — это тоже работает и переживает санитайзер.
<img src="./standalone.svg" alt="Production architecture" width="100%" />
## Плюсы / минусы
**+** Контроль над размером — большие SVG не раздувают preview.
**+** `max-width:100%` — адаптивно для мобильных.
**-** Это HTML в Markdown — некоторые plain-MD рендереры не поймут.
**-** Если указать фиксированный `width` слишком маленьким, SVG потеряет читаемость.
## Когда использовать
- Большие диаграммы (2000+ px) — фиксируй `max-width:1000px`
- Маленькие диаграммы — `width="600"` чтобы не было мелко
- Когда хочешь чтобы SVG растягивался в широких preview — `style="max-width:100%; height:auto;"`
## Связанные файлы
- `svg-embedded.md` — простой markdown вариант без sizing
- `standalone.svg` — собственно файл