Passa al contenuto principale

Official Badges & CI/CD Integration

Zenzic provides two official badge types. Add them to your project's README.md to signal documentation integrity to contributors and users.

🛡️ Zenzic Shield (Binary Status)​

Zenzic Shield badge

Use this badge for strict pipelines where any broken link, dead anchor, or leaked credential must block the build. It is a binary gate: passing or failing.

Copy-paste Markdown​

Passing (green):

[![Zenzic Shield](https://img.shields.io/badge/🛡️_zenzic_shield-passing-4f46e5?style=flat)](https://github.com/PythonWoods/zenzic)

Failing (red):

[![Zenzic Shield](https://img.shields.io/badge/🛡️_zenzic_shield-failing-ef4444?style=flat)](https://github.com/PythonWoods/zenzic)
- name: Lint documentation (Zenzic Shield)
  run: uvx zenzic check all --strict

Place the passing URL in your README. If this step fails in CI, manually swap the badge to failing — or automate it via dynamic-badges-action (see CI/CD Integration).

💯 Zenzic Score (Improvement Metric)​

Zenzic Score badge

Use this badge to expose the live quality score (0–100) of your documentation. Ideal for legacy projects adopting Zenzic progressively: a green build can still show a non-perfect score, encouraging continuous improvement without blocking the workflow.

Copy-paste Markdown​

[![Zenzic Score](https://img.shields.io/badge/🛡️_zenzic-100%2F100-4f46e5?style=flat)](https://github.com/PythonWoods/zenzic)

Using --fail-under for progressive adoption​

# Green CI at 72/100 — build passes, score is visible
zenzic score --fail-under=70

# Red CI at 72/100 — floor not met
zenzic score --fail-under=80

The --fail-under flag decouples the exit code from the score value. Teams can start at a realistic floor (e.g. 60) and raise it sprint by sprint.

📊 Live Score Badge via JSON​

zenzic score --save writes .zenzic-score.json at the repo root:

{"project": "zenzic", "score": 100, "threshold": 0, "status": "success", "timestamp": "...", "categories": [...]}

This file is the machine-readable bridge to dynamic Shields.io badges.

Automate with GitHub Actions​

The following two steps save the score and push it to a GitHub Gist that Shields.io reads on every request:

- name: Compute Zenzic Score
  run: |
    uvx zenzic score --save
    echo "SCORE=$(uvx zenzic score --format json | python3 -c \
      'import sys,json; print(json.load(sys.stdin)["score"])')" >> "$GITHUB_ENV"

- name: Update Score Badge
  uses: Schneegans/dynamic-badges-[email protected]
  with:
    auth: ${{ secrets.GIST_SECRET }}
    gistID: <your-gist-id>
    filename: zenzic-score.json
    label: "🛡️ zenzic"
    message: "${{ env.SCORE }} / 100"
    color: ${{ env.SCORE == '100' && '4f46e5' || env.SCORE >= '80' && 'f59e0b' || 'ef4444' }}

Then reference the dynamic endpoint in your README:

[![Zenzic Score](https://img.shields.io/endpoint?url=https://gist.githubusercontent.com/<user>/<gist-id>/raw/zenzic-score.json)](https://github.com/PythonWoods/zenzic)

Setup: create a Gist, generate a Personal Access Token with gist scope, save it as GIST_SECRET in your repo secrets, and replace <your-gist-id>. See CI/CD Integration for the complete workflow.

🎨 Offline / Enterprise Badges​

Projects in air-gapped or enterprise environments that cannot call img.shields.io can embed the official static SVG assets from the Brand Kit directly:

FileDescription
zenzic-badge-shield.svgStatic "passing" shield badge
zenzic-badge-score.svgStatic "100 / 100" score badge

Note: brand-kit.zip is a build artifact. It is not stored in the repository — download it from the GitHub Releases page, or generate it locally with nox -s preflight.