Configuration

Learn how to configure your subdomain with DNS records and additional settings.

To request a subdomain, you need to create a JSON configuration file that tells us how your subdomain should behave.

Each configuration file is added to the domains/ directory in the repository and must follow specific naming conventions.

Filename Requirements

Your configuration file must meet these criteria:

• Must be alphanumeric, in lowercase
• Dashes (-) may be used as separators
• Must be at least 1 character long
• Must have a .json file extension
• Must not contain the parent domain name

Invalid Filename Examples

• .json (filename is less than 1 character)
• A.json (contains uppercase letters)
• a..json (contains consecutive dots)
• .a.json (starts with a dot)
• a .json (contains a space)
• a$.json (contains non-alphanumeric character)
• a.json.json (multiple .json extensions)

Valid Filename Examples

• a.json (at least 1 character long)
• example.json (alphanumeric and lowercase)
• blog.example.json (includes dots for sub-subdomains)
• my-blog.json (uses dashes as separators)

Note: To prevent monopolization, users are limited to one one-letter subdomain.

Basic Structure

Here’s what a minimal configuration looks like:

{
  "description": "My personal website",
  "repo": "https://github.com/username/repo",
  "owner": {
    "username": "your-github-username",
    "email": "[e-mail]"
  },
  "records": {
    "CNAME": "username.github.io"
  },
  "proxied": false
}

Required Fields

owner

Information about the domain owner. This is required for communication if needed.

{
  "owner": {
    "username": "your-github-username",
    "email": "[e-mail]"
  }
}

records

Defines the DNS records for your subdomain. At least one record type is required.

Optional Fields

description

A brief description of your domain’s purpose (optional but recommended).

repo

Link to your website’s repository or GitHub account (optional).

proxied

Enable Cloudflare proxying for your domain (defaults to false).

{
  "proxied": true
}

Supported DNS Records

CNAME Record

Points your domain to another hostname.

{
  "records": {
    "CNAME": "username.github.io"
  }
}

A Record

Maps your domain to IPv4 addresses.

{
  "records": {
    "A": [
      "192.0.2.1",
      "198.51.100.1"
    ]
  }
}

AAAA Record

Maps your domain to IPv6 addresses.

{
  "records": {
    "AAAA": [
      "2001:0db8:85a3:0000:0000:8a2e:0370:7334"
    ]
  }
}

MX Record

Specifies mail servers for your domain.

{
  "records": {
    "MX": [
      {
        "target": "mx1.example.com",
        "priority": 10
      },
      {
        "target": "mx2.example.com",
        "priority": 20
      }
    ]
  }
}

TXT Record

Stores text information, often used for verification.

{
  "records": {
    "TXT": ["v=spf1 include:_spf.example.com ~all"]
  }
}

SRV Record

Defines service locations (e.g., VoIP, messaging, gaming servers).

{
  "records": {
    "SRV": [
      {
        "priority": 10,
        "weight": 5,
        "port": 8080,
        "target": "srv.example.com"
      }
    ]
  }
}

CAA Record

Controls which Certificate Authorities can issue SSL certificates.

{
  "records": {
    "CAA": [
      {
        "flags": 0,
        "tag": "issue",
        "value": "letsencrypt.org"
      }
    ]
  }
}

Important Notes

• Each domain requires its own configuration file
• JSON must be valid - use a JSON validator if needed
• Your subdomain request will be reviewed before approval
• You can update your configuration by submitting a new pull request
• Some record combinations may have restrictions (e.g., CNAME with other records)

Need help? Visit our Get Started guide or open an issue.