Configuration

Configuration Reference

The config.yaml file controls all aspects of your leaderboard system.

Configuration Schema

Organization (`org`)

Basic information about your organization.

org:
  name: string # required - Organization name
  description: string # required - Short description
  url: string (URL) # required - Organization website
  logo_url: string (URL) # required - Logo image URL
  start_date: string (date) # optional - Organization founding date
  socials: # optional - Social media links
    github: string (URL)
    slack: string (URL)
    linkedin: string (URL)
    youtube: string (URL)
    email: string (email)

Example:

org:
  name: Open Healthcare Network
  description: Building connected healthcare systems
  url: https://ohc.network
  logo_url: https://ohc.network/logo.svg
  start_date: 2020-03-08
  socials:
    github: https://github.com/ohcnetwork
    slack: https://slack.ohc.network

Meta (`meta`)

SEO and site metadata.

meta:
  title: string # required - Site title
  description: string # required - Site description
  image_url: string (URL) # required - OpenGraph image
  site_url: string (URL) # required - Canonical site URL
  favicon_url: string (URL) # required - Favicon URL

Example:

meta:
  title: OHC Contributors
  description: Track contributions across OHC projects
  image_url: https://ohc.network/og-image.png
  site_url: https://contributors.ohc.network
  favicon_url: https://ohc.network/favicon.ico

Leaderboard (`leaderboard`)

Leaderboard-specific configuration.

leaderboard:
  data_source: string # optional - Data source URL
  theme: string (URL) # optional - Custom theme CSS URL
  roles: # required - Role definitions
    [role_id]:
      name: string # required - Display name
      description: string # optional - Role description
      hidden: boolean # optional - Hide from leaderboard

  top_contributors: # optional - Activity slugs to highlight
    - string

  social_profiles: # optional - Social icon mappings
    [platform]:
      icon: string # Lucide icon name

  aggregates: # optional - Custom aggregates
    global: # Show on home page
      - string
    contributor: # Show on profile pages
      - string

  data_explorer: # optional - Data Explorer configuration
    enabled: boolean # optional - Enable/disable (default: true)
    source: string # optional - Database URL or path (default: "/data.db")

  plugins: # optional - Plugin configurations
    [plugin_id]:
      name: string # optional - Display name
      source: string (URL) # required - Plugin manifest URL
      config: # optional - Plugin-specific config
        [key]: any

  leaderboard: # optional - Leaderboard display settings
    all_contributors: # optional - All Contributors table options
      activity_definitions: # optional - Activity definition slugs to show as columns
        - string

Data Explorer (`data_explorer`)

The Data Explorer provides an in-browser SQL REPL powered by WebAssembly. It can be toggled on or off, and the database source can point to a local or external URL.

leaderboard:
  data_explorer:
    enabled: boolean # optional - Enable the Data Explorer (default: true)
    source: string # optional - URL or path to the database file (default: "/data.db")

Defaults: When the data_explorer key is omitted, the feature is enabled and uses /data.db (shipped as a static asset alongside the site).

Examples

Disable the Data Explorer entirely:

leaderboard:
  data_explorer:
    enabled: false

Host the database externally (e.g., on GitHub Pages to work around Cloudflare Pages' 25 MiB file size limit):

leaderboard:
  data_explorer:
    source: https://yourorg.github.io/leaderboard-data/data.db

When source is set to an external URL, the prebuild step skips copying the .db file into public/, keeping the deployed bundle small. The browser fetches the database directly from the external host using HTTP Range Requests.

See the Data Explorer documentation for detailed instructions on hosting the database on GitHub Pages.

Leaderboard Display (`leaderboard.leaderboard`)

Control what is shown in the leaderboard's "All Contributors" table.

Activity Definition Columns

By default, the All Contributors table does not show per-activity-type breakdown columns. To display specific activity types as individual columns, list their slugs:

leaderboard:
  leaderboard:
    all_contributors:
      activity_definitions:
        - pr_merged
        - pr_opened
        - commit_authored

Each listed slug corresponds to an activity definition created by your plugins. Only matching definitions will appear as columns in the table, showing per-contributor counts and icons.

When this configuration is omitted, no per-activity breakdown columns are shown — contributors are listed with their total points and trend only.

Role Configuration

Roles categorize contributors and can be filtered in the leaderboard.

Example:

leaderboard:
  roles:
    core:
      name: Core Team
      description: Full-time team members

    intern:
      name: Intern
      description: Internship participants

    contributor:
      name: Open Source Contributor
      description: Community contributors

    bot:
      name: Bot Account
      description: Automated accounts
      hidden: true # Exclude from leaderboard

Plugin Configuration

Plugins extend the system with new data sources.

Basic Plugin:

leaderboard:
  plugins:
    github:
      name: GitHub Activity Tracker
      source: https://example.com/plugins/github.js
      config:
        githubToken: ${{ env.GITHUB_TOKEN }}
        githubOrg: myorg
        repositories:
          - repo1
          - repo2

Local Plugin:

leaderboard:
  plugins:
    custom:
      source: file:///absolute/path/to/plugin.js
      config:
        apiKey: ${{ env.API_KEY }}

Environment Variables

In Config

Use environment variables in config.yaml:

leaderboard:
  plugins:
    github:
      config:
        token: ${{ env.GITHUB_TOKEN }}
        org: ${{ env.GITHUB_ORG }}

System Variables

Set these in your environment:

# Data directory location
export LEADERBOARD_DATA_DIR=/path/to/data-repo

# Database URL (optional)
export LIBSQL_DB_URL=file:/path/to/custom.db

# Plugin-specific variables
export GITHUB_TOKEN=ghp_xxx
export SLACK_API_TOKEN=xoxb-xxx

Map social platform identifiers to Lucide icons:

leaderboard:
  social_profiles:
    github:
      icon: github
    linkedin:
      icon: linkedin
    twitter:
      icon: twitter
    email:
      icon: mail
    website:
      icon: globe

Then in contributor profiles:

---
username: alice
social_profiles:
  github: https://github.com/alice
  linkedin: https://linkedin.com/in/alice
---

Top Contributors

Highlight specific activity types in the sidebar:

leaderboard:
  top_contributors:
    - pr_merged
    - issue_opened
    - release_published

Custom Aggregates

Define custom statistics to display:

leaderboard:
  aggregates:
    global: # Home page stats
      - total_activities
      - count_contributors
      - pr_avg_tat # Custom aggregate

    contributor: # Profile page stats
      - total_points
      - total_activities
      - streak_days # Custom aggregate

Aggregates must be computed by plugins or in the Next.js app.

Theme Customization

Override the default theme:

leaderboard:
  theme: https://raw.githubusercontent.com/myorg/data/main/theme.css

The theme CSS file can override any CSS variables or classes.

Role Badge Colors

Role badges render with a data-contributor-role attribute set to the role key (e.g., core, intern, contributor). You can customize badge colors per role in your theme.css:

/* Style badges for the "core" role */
[data-contributor-role="core"] {
  background-color: oklch(0.65 0.18 145);
  color: white;
}

/* Style badges for the "intern" role */
[data-contributor-role="intern"] {
  background-color: oklch(0.7 0.15 250);
  color: white;
}

/* Style badges for the "contributor" role */
[data-contributor-role="contributor"] {
  background-color: oklch(0.75 0.12 60);
  color: black;
}

Use any valid CSS for styling — background-color, color, border, etc. The attribute selector [data-contributor-role="<role_key>"] matches the role keys defined in your config.yaml under leaderboard.roles.

Validation

Config is validated at runtime using Zod schemas. Invalid configurations will fail with detailed error messages:

Configuration validation failed:
  - org.url: Invalid url
  - leaderboard.roles: Required
  - leaderboard.plugins.github.source: Invalid url

Complete Example

org:
  name: Acme Corp
  description: Building amazing products
  url: https://acme.com
  logo_url: https://acme.com/logo.svg
  socials:
    github: https://github.com/acme

meta:
  title: Acme Contributors
  description: Recognizing our amazing contributors
  image_url: https://acme.com/og.png
  site_url: https://contributors.acme.com
  favicon_url: https://acme.com/favicon.ico

leaderboard:
  roles:
    employee:
      name: Employee
    contractor:
      name: Contractor
    contributor:
      name: Open Source Contributor

  top_contributors:
    - pr_merged
    - release_published

  leaderboard:
    all_contributors:
      activity_definitions:
        - pr_merged
        - pr_opened
        - commit_authored

  social_profiles:
    github:
      icon: github
    linkedin:
      icon: linkedin

  data_explorer:
    source: https://acme.github.io/leaderboard-data/data.db

  plugins:
    github:
      source: https://cdn.acme.com/plugins/github.js
      config:
        token: ${{ env.GITHUB_TOKEN }}
        org: acme
        repos:
          - frontend
          - backend

    slack:
      source: https://cdn.acme.com/plugins/slack.js
      config:
        token: ${{ env.SLACK_TOKEN }}
        channel: ${{ env.SLACK_CHANNEL }}

Configuration

On this page