Markdown Checklist & Task List Matrix

What does the Markdown Task List Matrix do?

The Markdown Checklist & Task List Progress Matrix parses GitHub Flavored Markdown (GFM) task items (- [ ] and - [x]) across documents, issues, and project README files. It calculates real-time completion statistics, generates copy-pasteable visual ASCII progress bars ([████████░░] 80%), builds dynamic Shields.io status badges, and provides interactive checkbox toggles.

Engineering leads, open-source maintainers, and DevOps engineers use this utility to track sprint deliverables, automate PR checklist validation, format release roadmaps, and archive completed tasks.

Core Concepts & Task Syntax

Markdown task lists follow the GitHub Flavored Markdown specification:

• Syntax Format: A bullet (-, *, +, or 1.) followed by [ ] (unchecked/pending) or [x] / [X] (checked/completed).
• Nested Hierarchies: Supports tab or space-indented sub-tasks and sub-checklists.
• ASCII Progress Bars: Text-based progress indicators ([████░░░░░░] 40%) that render cleanly in plain text files, Git commit logs, and release summaries.
• Dynamic Shields Badges: Generates color-coded Shields.io badges based on completion percentage (green for 100%, blue for 70%+, yellow for 40%+, red for <40%).

How to use the tool?

1. Paste Markdown Task List: Paste your Markdown roadmap, sprint list, or README document containing - [ ] or - [x] items.
2. Analyze Progress: Click 📊 Analyze Checklist Progress to view completion percentages, total task counts, and visual progress bars.
3. Interactive Toggles & Quick Actions: Check or uncheck items directly in the visual matrix, click ✓ Mark All Completed, ◻ Mark All Pending, or 📦 Archive Completed to isolate finished tasks into the footer.
4. Copy & Embed: Copy the synchronized Markdown document along with progress badges into your repository.

REST API Integration

Blueutils provides a free REST API endpoint (POST https://blueutils.com/api/markdown/task-list-matrix) for programmatic integration.

API Request Parameters

API Request Payload Examples

cURL

curl -X POST https://blueutils.com/api/markdown/task-list-matrix \
  -H "Content-Type: application/json" \
  -d '{
    "rawText": "## Roadmap\n- [x] Task 1\n- [ ] Task 2\n- [x] Task 3",
    "action": "analyze"
  }'

Python

import requests

url = "https://blueutils.com/api/markdown/task-list-matrix"
payload = {
    "rawText": "## Roadmap\n- [x] Task 1\n- [ ] Task 2\n- [x] Task 3",
    "action": "analyze"
}
headers = {"Content-Type": "application/json"}
response = requests.post(url, json=payload, headers=headers)
print(response.json())

Java

import java.net.URI;
import java.net.http.HttpClient;
import java.net.http.HttpRequest;
import java.net.http.HttpResponse;

public class Main {
    public static void main(String[] args) throws Exception {
        String jsonPayload = "{\"rawText\":\"- [x] Task 1\\n- [ ] Task 2\",\"action\":\"analyze\"}";
        HttpClient client = HttpClient.newHttpClient();
        HttpRequest request = HttpRequest.newBuilder()
            .uri(URI.create("https://blueutils.com/api/markdown/task-list-matrix"))
            .header("Content-Type", "application/json")
            .POST(HttpRequest.BodyPublishers.ofString(jsonPayload))
            .build();
        HttpResponse<String> response = client.send(request, HttpResponse.BodyHandlers.ofString());
        System.out.println(response.body());
    }
}

API Response Parameters

API Response Payload Examples

Success Response (HTTP 200 OK)

{
  "isValid": true,
  "totalTasks": 3,
  "completedTasks": 2,
  "pendingTasks": 1,
  "percentage": 67,
  "textProgressBar": "[███████░░░] 67% (2/3 completed)",
  "progressBadgeUrl": "https://img.shields.io/badge/tasks-2%2F3_completed_(67%25)-blue",
  "progressBadgeMarkdown": "![Task Progress](https://img.shields.io/badge/tasks-2%2F3_completed_(67%25)-blue)"
}

Validation Failure Response (HTTP 400 Bad Request)

{
  "isValid": false,
  "error": "No Markdown task checkboxes (- [ ] or - [x]) were found in the provided text."
}

Rate Limit Exceeded Response (HTTP 429 Too Many Requests)

{
  "error": "API rate limit exceeded. Please wait or contact support@blueutils.com."
}

Why use an API to analyze Markdown task lists?

Integrating the Markdown Task List API into CI/CD pipelines, GitHub bots, or webhook automation provides several practical advantages:

• Automated Pull Request Gates: Automatically calculate checklist completion on GitHub PR descriptions and block merging until 100% of required checklist items are checked.
• Dynamic Release Badges: Generate real-time task progress badges for project dashboards without manual counter updates.
• Sprint Archiving Automation: Programmatically move finished checklist items to an archive header at the end of each sprint.

Native Usage

How to count and process Markdown task list checkboxes locally using native command-line utilities and scripts:

Windows (PowerShell Task Counter)

# Count Markdown tasks and calculate progress in PowerShell
$content = Get-Content README.md
$total = ($content | Select-String '[-*+]\s+\[[ xX]\]').Count
$done = ($content | Select-String '[-*+]\s+\[[xX]\]').Count
$percent = if ($total -gt 0) { [math]::Round(($done / $total) * 100) } else { 0 }
Write-Output "Progress: $done / $total ($percent%)"

Linux / Unix (Grep & AWK CLI Pipeline)

# Calculate Markdown checklist progress in Bash
total=$(grep -cE '^ *[-*+] \[[ xX]\]' README.md)
done=$(grep -cE '^ *[-*+] \[[xX]\]' README.md)
percent=$(( done * 100 / total ))
echo "Progress: $done/$total (${percent}%)"

Python (Standard Library Task Counter)

import re

with open("README.md", "r", encoding="utf-8") as f:
    text = f.read()

tasks = re.findall(r'^ *[-*+] \[([ xX])\]', text, re.MULTILINE)
total = len(tasks)
completed = sum(1 for t in tasks if t.lower() == 'x')
percent = round((completed / total) * 100) if total else 0
print(f"Progress: {completed}/{total} ({percent}%)")

Java (Native Standard Library Task Scanner)

import java.nio.file.Files;
import java.nio.file.Path;
import java.util.regex.Matcher;
import java.util.regex.Pattern;

public class TaskCounter {
    public static void main(String[] args) throws Exception {
        String md = Files.readString(Path.of("README.md"));
        Matcher m = Pattern.compile("(?m)^\\s*[-*+]\\s+\\[([ xX])\\]").matcher(md);
        int total = 0, done = 0;
        while (m.find()) {
            total++;
            if (m.group(1).equalsIgnoreCase("x")) done++;
        }
        int percent = total > 0 ? (done * 100 / total) : 0;
        System.out.println("Progress: " + done + "/" + total + " (" + percent + "%)");
    }
}