Markdown tasks progress badge

🗺️ Overview

A Go server app that generates progress bar badges

md endpoint takes url encoded markdown url, calculate the percentage based on checkboxes - [ ] and - [x] and return a progress badge

value endpoint just take the percentage in the path

Forked from this repo https://github.com/gepser/markdown-progress ⭐

💡 Examples

Tip

Don't hesitate to host it yourself but every snippet below is ready to paste into GitHub Markdown.

Markdown checkbox percentage

Markdown example : test-todo.md

Note

![progress badge](https://md-badge.ad2ien.dev/md?url=https%3A%2F%2Fraw.githubusercontent.com%2Fad2ien%2Fmd-tasks-progress-badge%2Frefs%2Fheads%2Fmain%2Ftest-todo.md)

Integer percentage

Note

![progress badge](https://md-badge.ad2ien.dev/value/10)

Float percentage

Note

![progress badge](https://md-badge.ad2ien.dev/value/76.5)

Custom threshold colors (dangerColor, warningColor, successColor)

Note

![progress badge](https://md-badge.ad2ien.dev/value/50?dangerColor=800000&warningColor=ff9900&successColor=006600)

Fixed bar color (barColor)

Note

![progress badge](https://md-badge.ad2ien.dev/value/50?barColor=4472C4)

Data-bar mode (min + max + label + barColor)

Note

![progress badge](https://md-badge.ad2ien.dev/value/186?label=186&min=0&max=241&barColor=4472C4)

Data-bar mode with default label (raw value)

Note

![progress badge](https://md-badge.ad2ien.dev/value/50?min=0&max=200)

Custom text label in percentage mode

Note

![progress badge](https://md-badge.ad2ien.dev/value/70?label=Sprint%201)

📜 API Contract

Endpoint

• GET /{percentage}
• HEAD /{percentage}

percentage can be an integer or float and is clamped to 0..100.

• GET /md-progress?url={url}
• HEAD /md-progress?url={url}

url URL encoded of a markdown file containing checkboxes

Query params

• dangerColor
• warningColor
• successColor
• barColor (overrides the bar fill color)
• label (custom text inside the bar, max 64 chars)

All color values must be 6-character hex values without # (example: ff9900).

Only for / endpoint:

• min
• max

min and max must be provided together when used.

Response behavior

• 200 OK: valid request, returns SVG.
• 400 Bad Request: invalid numeric input, range config, label length, or color format.
• 405 Method Not Allowed: any method different from GET or HEAD.
• 500 Internal Server Error: template parse/render failure.

Headers for successful responses:

• Content-Type: image/svg+xml
• Cache-Control: public, max-age=300

Tip

percentage values outside 0..100 are accepted and clamped automatically.

🛠️ Local Development

Environments

• The entry point for GCP function is serverless.go and cmd/main.go is not included
• For docker : serverless.go is not included and there's no dependency
• Locally : use cmd/main.go with unused GoogleCloudPlatform function dependency

Prerequisites

• Just
• Docker

This is for contained build and run but set up you're environment how you like.

Run locally:

just run

Try it in a browser:

http://localhost:1983/76

Quality checks

just check

Smoke tests against deployed URL

just smoke http://localhost:1983

The smoke test validates status codes, headers, and basic content contract.

☁️ Deploy (Google Cloud)

Set your project first:

gcloud auth login
gcloud config set project THE_PROJECT_NAME

Deploy as an HTTP function with Progress as entrypoint:

gcloud functions deploy progress --gen2 --runtime go125 --entry-point Progress --trigger-http --allow-unauthenticated --region us-central1

Important

This endpoint is intentionally public (allUsers invoker) so it can be used directly from markdown image links across repos.

All the details in ./scripts/gcp-setup.sh and .github/workflow/deploy.yml

🧩 One-time GCP setup (OIDC/WIF, no JSON keys)

Run setup script : script/gcp-setup.sh

🐳 Docker image

A docker image is created by the CI

docker run -p 1983:1983 ghcr.io/ad2ien/md-tasks-progress-badge:latest

Usage :

• http://localhost:1983/value/75
• http://localhost:1983/md?url=$ENCODED_MD_URL

🤖 Automated Deploy (GitHub Actions -> GCP)

This repo includes .github/workflows/deploy.yml to deploy automatically on push to main (and manually via workflow_dispatch).

🔐 Configure GitHub repository variables

Required:

• GCP_PROJECT_ID (example: progress-markdown)
• GCP_WORKLOAD_IDENTITY_PROVIDER (full resource name)
• GCP_SERVICE_ACCOUNT (deployer service account email)

Optional (defaults are already set in workflow):

• GCP_REGION (us-central1)
• GCP_FUNCTION_NAME (progress)
• GCP_RUNTIME (go125)
• GCP_ENTRY_POINT (Progress)

✅ CI/CD

• CI workflow runs go test and go vet on pushes and PRs.
• Smoke Tests workflow can be run manually (workflow_dispatch) with a base_url input.
• Deploy workflow deploys to GCP using OIDC/WIF.
• docker build and push docker image to gh registry