docs(badges): replace img.shields.io with native self-hosted SVG badges#65
Merged
Conversation
## Why shields.io is great for prototypes, but for a shipped product it brings real downsides: - **Outage exposure** — if shields.io goes down, all 5 badges in our README turn into red error icons - **Network dependency** — offline / CI-behind-firewall users see broken images - **Privacy leak** — every README view sends a request with User-Agent and Referer to a third-party CDN - **Style drift** — third-party rendering can change without notice - **Brand inconsistency** — the colors/typography don't match our SceneFab 3-color logo system ## What changed 5 self-hosted SVG badges under `assets/badges/`, synced to `docs/public/badges/` for the VitePress docs site: | Badge | Path | Color story | |-------|------|-------------| | License: MIT | license-mit.svg | Indigo gradient (`#6366F1 → #4F46E5`) | | Python 3.10+ | python.svg | Python blue (`#41A5DB → #2B7CB3`) | | PySide6 Qt 6.9 | pyside6.svg | Qt green (`#52C752 → #2E8B2E`) | | Platform | platform.svg | Neutral gray (`#9CA3AF → #6B7280`) | | Version v1.1.0 | version.svg | **SceneFab brand orange-red** (`#ff8a5b → #e63946`) | All 5 SVGs: - 28px tall, for-the-badge style - Verdana bold 11px text, accessible (role=img + aria-label + <title>) - Validated as XML ## Automation `scripts/generate_badges.py` reads the version from `pyproject.toml` and regenerates `assets/badges/version.svg`: ```bash python scripts/generate_badges.py # regenerate python scripts/generate_badges.py --check # CI: exit 1 if drift ``` CI integration TODO: add a `make badges` or pre-commit hook so version bumps always stay in sync. ## .gitignore fix The previous `docs/` and `assets/` rules were too broad — they prevented tracking any new resources in those directories. Replaced with build-output-specific rules (`docs/build/`, `docs/.vitepress/dist/`, `docs/.vitepress/cache/`, `assets/build/`, `assets/dist/`). ## Files - 5 new badge SVGs in `assets/badges/` - 5 sync copies in `docs/public/badges/` (VitePress) - 1 new generator script: `scripts/generate_badges.py` - README.md: 5 shields.io URLs → 5 local SVG paths + inline HTML comment block documenting the decision - .gitignore: build-artifact rules narrowed to actual build outputs
4 tasks
Agions
added a commit
that referenced
this pull request
Jun 2, 2026
) 主人偏好确认: 徽标用业界原生 shields.io (img.shields.io), 不用自定义 SVG. Changes: - 删除 10 个自定义 SVG (assets/badges/* + docs/public/badges/*) - 删除 scripts/generate_badges.py - 还原 .gitignore (docs/ + assets/ 整个 ignore) - README.md 改回 shields.io 5 行标准 Markdown 徽标 shields.io 是 GitHub 生态最常用的'原生'徽标方案, 所有顶级 OSS 项目都用 (React, Vue, TensorFlow 等). 自定义 SVG 反而 是偏离惯例. Refs: PR #65
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
1 participant
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
徽标原生化 (Self-hosted Badges)
🎯 Why
shields.io适合原型, 但对 ship 出去的产品有实际风险:🎨 5 个自托管 SVG 徽标
assets/badges/license-mit.svg#6366F1 → #4F46E5)assets/badges/python.svg#41A5DB → #2B7CB3)assets/badges/pyside6.svg#52C752 → #2E8B2E)assets/badges/platform.svg#9CA3AF → #6B7280)assets/badges/version.svg#ff8a5b → #e63946)统一规格: 28px 高, for-the-badge 风格, Verdana 11px 粗体, 全部含
role="img"+aria-label+<title>(无障碍)🤖 自动化
新增
scripts/generate_badges.py从pyproject.toml读 version 自动生成 version 徽标:🔧 附带修复 .gitignore
旧
docs/+assets/规则太宽 (阻止任何资源目录被 track), 改为精确 build-output 规则:docs/build/docs/.vitepress/dist/docs/.vitepress/cache/assets/build/assets/dist/📋 文件清单
assets/badges/*.svgdocs/public/badges/*.svg(VitePress 文档站)scripts/generate_badges.py✅ 验证
ruff check src/scenefab/0 errorsgenerate_badges.py --checkv1.1.0 同步rg img.shields.io无残留📋 Post-merge (可选 TODO)
python scripts/generate_badges.py --checkgenerate_badges.py自动同步 version 徽标