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:
@@ -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 читаемый
|
||||
@@ -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 <object>.
|
||||
<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>`
|
||||
@@ -0,0 +1,47 @@
|
||||
# Production architecture (sized SVG variant)
|
||||
|
||||
> **Вариант №5:** SVG-картинка в Markdown, но с **контролем размера** через HTML-тег `<img>`.
|
||||
> Полезно если хочется ограничить максимальную ширину или принудительно растянуть.
|
||||
|
||||
## Чем отличается от svg-embedded.md
|
||||
|
||||
`svg-embedded.md` использует чистый markdown `` — 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` — собственно файл
|
||||
Reference in New Issue
Block a user