Quick Start Guide

This guide will walk you through getting your first *.loves-to.dev subdomain from start to finish. You’ll have a working subdomain in under 24 hours!

What You’ll Need

Before starting, make sure you have:

✅ A GitHub account
✅ A website or app to host (GitHub Pages, Vercel, Netlify, etc.)
✅ A valid email address
✅ 5 minutes of your time

Step 1: Choose Your Subdomain

Pick a username that will become your subdomain:

✅ Allowed: lowercase letters (a-z), numbers (0-9), hyphens (-)
❌ Not allowed: uppercase, special characters, underscores
❌ Reserved: www, api, admin, docs, mail, etc.

Example: If you choose alice, you’ll get alice.loves-to.dev

Step 2: Fork Our Repository

Go to github.com/loves-to-dev/register
Click the “Fork” button in the top-right corner
This creates your own copy where you can make changes

Step 3: Create Your Domain File

In your forked repository, navigate to the domains/ folder
Click “Add file” → “Create new file”
Name your file exactly: yourusername.json (replace with your chosen username)

Important: The filename must match your username exactly!

Step 4: Add Your Configuration

Copy this template and customize it:

{
  "owner": {
    "username": "yourusername",
    "email": "your@email.com"
  },
  "records": {
    "CNAME": "yourusername.github.io"
  }
}

Common CNAME Examples:

// GitHub Pages
"CNAME": "alice.github.io"

// Vercel
"CNAME": "cname.vercel-dns.com"

// Netlify
"CNAME": "amazing-site-123.netlify.app"

// Custom domain
"CNAME": "portfolio.alice.dev"

Step 5: Submit Your Pull Request

Scroll down to the “Commit new file” section
Add a commit message like: Add alice subdomain
Select “Create a new branch for this commit and start a pull request”
Click “Propose new file”
On the next page, click “Create pull request”

Step 6: Wait for Validation

Our automated system will check your submission:

🤖 Automated checks run immediately
✅ Green checkmarks = everything looks good!
❌ Red X = something needs fixing (check the error message)

Common validation errors:

Filename doesn’t match username
Invalid email format
Reserved username
Invalid CNAME target

Step 7: Get Approved

👥 A maintainer will review your PR (usually within 24 hours)
💬 They might ask for changes if needed
✅ Once approved, your PR gets merged
🚀 DNS updates automatically within minutes!

Step 8: Configure Your Hosting Platform

While waiting for approval, set up your hosting platform:

For GitHub Pages:

Go to your repository → Settings → Pages
Set source to your main branch
Add yourusername.loves-to.dev as custom domain
Enable “Enforce HTTPS”

For Other Platforms:

Step 9: Test Your Subdomain

Once approved and DNS has propagated:

Visit https://yourusername.loves-to.dev
You should see your website!
Check for the green padlock (HTTPS working)

DNS propagation can take 5-30 minutes, sometimes up to 48 hours globally.

Troubleshooting

My PR has red X marks

Read the error message carefully
Fix the issue and push new changes
The validation will run again automatically

”This site can’t be reached”

DNS might still be propagating (wait 30 minutes)
Check if your hosting platform is configured correctly
Verify your CNAME target is correct

SSL certificate warnings

Wait 5-10 minutes for automatic SSL provisioning
Make sure your hosting platform supports HTTPS
Some platforms take up to 24 hours for SSL

What’s Next?

🎉 Congratulations! You now have your own loves-to.dev subdomain!

Optional Next Steps:

📈 Set up analytics (Google Analytics, Plausible)
🎨 Customize your site design
📱 Make it mobile-friendly
🔍 Add SEO meta tags
⚡ Optimize for performance

Join the Community:

⭐ Star our repository to show support
🐛 Report issues or suggest improvements
🤝 Help other developers by contributing to docs

Need Help?

Stuck on any step? We’re here to help:

📚 Check our troubleshooting guide
📧 Email us at support@loves-to.dev
🐛 Create an issue on GitHub

That’s it! You’re now part of the loves-to.dev community. Welcome aboard! 💖