Help and Documentation

What is Whatchan Darts?

Whatchan Darts is a comprehensive, self-updating darts statistics website covering the PDC (Professional Darts Corporation) circuit. It provides player profiles, tournament information, match predictions, TV schedules, and educational guides for fans of professional darts.

The site is built as a static HTML/CSS/JavaScript application with no backend server required. It can be hosted on any web server, GitHub Pages, or even opened directly from a local file system. Despite being static, it keeps itself up to date through a combination of:

• GitHub Actions - A daily automated scraper updates ranking and prize money data
• TheSportsDB API - Player images and biographical data are fetched live from a free API
• Date-driven logic - Tournament schedules, TV listings, and countdowns automatically adjust based on the current date

Complete Feature List

Player Profiles

Whatchan Darts contains detailed profiles for 102 players covering the full PDC Order of Merit top 100 (plus tied positions). Each profile includes:

• Hero banner with photo (from TheSportsDB API), name, nickname, nationality, ranking, age, darts used, walk-on music
• Stats strip showing Career Average, Recent Average, Checkout %, 180s/Leg, Major Titles, Prize Money
• Animated stat bars visualising performance metrics with colour coding (red for averages, gold for bests, teal for finishing)
• Recent form showing last 10 match results as W/L dots
• Biography (hand-written editorial) plus extended biography from TheSportsDB API when available
• Social media links (Twitter, Instagram, Facebook) from TheSportsDB API
• Head-to-head comparison selector (see below)
• Known H2H records against other players in the database
• Major titles list
• Strengths and weaknesses analysis
• Player details table (DOB, darts, walk-on, best checkout, prize money)

What auto-updates

Rankings and prize money update daily via the GitHub Actions scraper. Player images refresh from TheSportsDB (cached for 24 hours). Editorial content (bios, strengths, weaknesses, H2H records) is hand-written and requires manual updates.

Head-to-Head Comparison

Every player profile includes an interactive head-to-head comparison widget. Select any opponent from the dropdown (all 102 players, sorted by ranking) and the widget shows:

• H2H win record - displayed as a split bar with percentages (red vs teal) if records exist in the database
• Stat comparison table - Career Average, Recent Average, Checkout %, 180s/Leg, Major Titles, World Ranking, Prize Money. Each stat is colour-coded green (advantage) or red (disadvantage)
• "Run Full Prediction" button - links to the Result Predictor page with both players pre-selected, automatically running the full prediction model

H2H Database

The head-to-head database currently contains 35+ recorded matchups between top players. These are historical win/loss records with notes (e.g. "Including the 2024 World Championship final"). When no H2H record exists between two players, the widget shows "No record available" but still displays the full stat comparison.

The H2H database is stored in js/app.js in the H2H object. Records are keyed as "player1-id|player2-id" with p1Wins, p2Wins, and note fields. To add new records, add entries to this object.

Result Predictor

The Result Predictor uses a weighted statistical model to forecast match outcomes between any two players. It analyses eight factors:

Win probabilities are clamped to a 15%-85% range to reflect the inherent unpredictability of darts.

URL Parameters

The predictor accepts pre-filled players via URL parameters:

When both parameters are provided, the prediction runs automatically on page load. This is how the "Run Full Prediction" button on player profiles works.

Tournament Calendar

The tournament database contains 87 events for the 2026 PDC season, categorised into:

Each tournament includes: name, venue, dates, prize fund, format, number of players, defending champion, TV broadcaster, and description. The calendar page has filter chips for each category.

Tournament display is date-driven. The homepage countdown, TV schedule, and "Upcoming Tournaments" section automatically adjust based on the current date. No manual intervention is needed as the season progresses.

TV Schedule - "What Channel is the Darts On?"

The TV Schedule page automatically categorises upcoming events into: On Today, This Week, Coming Up (next 14 days), and Full Schedule. Each event shows colour-coded channel badges:

• Sky Sports - Blue badge (majority of major events)
• ITV - Yellow badge (UK Open, European Championship, PC Finals)
• PDC TV - Red badge (Pro Tour, Development events)
• DAZN - Grey badge (international streaming)
• Viaplay - Purple badge (Nordic streaming)

The schedule is generated from the tournament database's tv field and the parseDateRange() function. It updates automatically as dates pass.

Rankings (Order of Merit)

The Rankings page displays the full PDC Order of Merit as a sortable table showing: Rank, Player, Nationality, Career Average, Checkout %, Major Titles, Prize Money, and Recent Form.

Rankings and prize money auto-update daily via the GitHub Actions pipeline (see below). The "Rankings updated" date is shown at the top of the page.

Auto-Updating System

Whatchan Darts uses a layered data approach to stay evergreen without a backend server:

Layer 1: Hardcoded Data (app.js)

The JavaScript file contains the full player database (102 players), tournament calendar (87 events), H2H records (35+ matchups), checkout chart, and glossary. This is the editorial layer - bios, strengths, weaknesses, nicknames, walk-on songs. It serves as the fallback if any live data fails to load.

Layer 2: Live Rankings (data/rankings.json)

A JSON file updated daily by GitHub Actions. Contains current ranking positions and prize money for 129 players. On page load, app.js fetches this file and overlays the live data onto the hardcoded players, updating their ranking and prizeMoney fields. If the fetch fails, hardcoded data is used silently.

Layer 3: API Data (TheSportsDB)

Player images, extended biographies, and social media links are fetched live from the free TheSportsDB API. Results are cached in localStorage for 24 hours to respect the API's rate limit (30 requests/minute). If the API is unavailable, flag emojis are shown as fallback avatars.

Layer 4: Date-Driven Logic

Tournament schedules, TV listings, countdown timers, and "On Today" indicators all use JavaScript date comparisons against the current date. No data changes are needed as the season progresses - the display adapts automatically.

GitHub Integration

The project is hosted on GitHub at github.com/Dj4beat/darts-hub (private repository).

Repository Structure

The GitHub repository contains the complete site source code plus the automation pipeline. The Server/ folder (deployment zip) is excluded via .gitignore.

GitHub Actions Workflow

File: .github/workflows/update-rankings.yml

This workflow runs automatically every day at 06:00 UTC. It can also be triggered manually from the GitHub Actions tab. Here is what it does:

1. Checks out the repository
2. Sets up Python 3.12
3. Runs scripts/update-rankings.py
4. The script fetches the live PDC Order of Merit from dartsrankings.com
5. Parses the HTML table to extract rank, player name, and prize money for 128+ players
6. Writes the results to data/rankings.json
7. If the data has changed, commits and pushes automatically
8. If the data hasn't changed (no ranking events since last scrape), no commit is made

Cost

Completely free GitHub Actions provides 2,000 minutes/month on free accounts. This workflow uses approximately 10 seconds per run, totalling roughly 5 minutes per month.

Manual Trigger

To trigger an immediate rankings update:

1. Go to github.com/Dj4beat/darts-hub/actions
2. Click Update PDC Rankings in the left sidebar
3. Click Run workflow
4. Click the green Run workflow button

The workflow takes about 20 seconds. Once complete, data/rankings.json will be updated with a commit from "GitHub Actions Bot".

SSH Authentication

The local development environment uses SSH key authentication to push to GitHub. The key is stored at ~/.ssh/id_ed25519 and is registered on the GitHub account. No passwords are needed for git push operations.

Technical Architecture

Stack

• Frontend: HTML5, CSS3, vanilla JavaScript (no frameworks, no build step)
• Data: Hardcoded JS arrays + JSON file + TheSportsDB REST API
• Automation: Python 3.12 scraper + GitHub Actions
• Version control: Git + GitHub (SSH)
• Hosting: Any static web server (no backend required)

Design System

• Theme: Dark mode with red (#e63946), gold (#f4a261), and teal (#2a9d8f) accents
• Fonts: Inter (headings/body), JetBrains Mono (numbers/data)
• Layout: CSS Grid and Flexbox, max-width 1320px container
• Components: Glassmorphic cards with backdrop-filter, animated stat bars, colour-coded badges
• Responsive: Mobile breakpoint at 600px

JavaScript Architecture

All JavaScript is contained in a single IIFE (Immediately Invoked Function Expression) in js/app.js. The file is approximately 5,100 lines and includes:

• PLAYERS array - 102 player objects with full stats and editorial data
• H2H object - 35+ head-to-head records
• TOURNAMENTS array - 87 tournament objects with dates, venues, TV, formats
• CHECKOUTS object - Complete checkout chart (170 to 2)
• GLOSSARY array - 40+ term definitions
• Predictor engine - 8-factor weighted prediction algorithm
• API integration - TheSportsDB fetch with image cache
• Live data merge - Rankings JSON overlay on hardcoded data
• Page initialisers - One function per page type, dispatched on DOMContentLoaded

Data Sources

All data sources are free. The total ongoing cost of running Whatchan Darts is zero.

File Structure

Total: 30 HTML pages, ~5,100 lines of JavaScript, ~1,400 lines of CSS, 102 player profiles, 87 tournaments.

Deployment

Server Deployment

The Server/darts-hub.zip file contains everything needed to deploy. Upload and extract to any web server. The site requires no PHP, Node.js, databases, or server-side processing. Any host that serves static HTML files will work.

For the auto-updating rankings to work on the deployed site, you need to periodically sync the data/rankings.json file from the GitHub repository. Options:

• Manual: Download the latest zip after rankings update
• Git pull: If your server supports git, clone the repo and set up a cron job to pull daily
• GitHub Pages: Deploy directly from the GitHub repo for zero-maintenance hosting (free)

Local Development

Open index.html directly in a browser. Most features work without a server. The TheSportsDB API calls require a web server context due to CORS - use any local server:

Then visit http://localhost:8000.

Updating Content