Developer & Contributor Guide

Developer & Contributor Guide

Everything you need to know to submit a theme, understand the project structure, and work with the tooling.

---

Table of Contents

• Requirements
• Folder Structure
• Theme File Format
• Submitting a Theme
• Auto-Merge Rules
• themecmd Reference
• Common Issues

---

Requirements

Before submitting, make sure you have:

• A GitHub account
• Basic knowledge of CSS
• Discord with BetterDiscord or Vencord installed for testing
• Git installed locally (recommended)

You must be an approved collaborator to have your theme auto-merged. If this is your first submission, open an issue introducing yourself and the repo owner will add you.

---

Folder Structure

Each contributor owns one top-level folder. All your themes live inside it.

discord-themes/
├── Silver Themes/          ← Silverfox0338's themes
│   └── My Theme/
│       └── my-theme.css
├── 8Bit Themes/            ← 8Bit's themes
│   └── Dr. Stone/
│       └── dr.stone.css
└── Your Name Themes/       ← your folder (one per contributor)
    └── Your Theme/
        └── your-theme.css

Rules:

• Your folder name should follow the pattern [Name] Themes
• Each theme gets its own subfolder
• Only the folder owner may add, edit, or delete files inside it
• You cannot touch another contributor's folder

---

Theme File Format

Every theme must be a .css file with a metadata header block at the top. This block is what populates the README automatically — so fill it out properly.

/**
 * @name Theme Name
 * @author Your Name
 * @version 1.0.0
 * @description A short description of your theme.
 */

/* your CSS below */

Field	Required	Description
@name	Yes	Display name shown in the README and Discord
@author	Yes	Your name (should match your folder's author entry)
@version	Yes	Semantic version — start at 1.0.0
@description	Yes	One or two sentences describing the theme

Missing any of these will cause the doctor check to warn and may affect how your theme appears in the README.

Raw URL

Users install themes via the raw GitHub URL rather than downloading the file. Once your theme is merged, the raw URL will be:

https://raw.githubusercontent.com/Silverfox0338/discord-themes/main/Your%20Name%20Themes/Your%20Theme/your-theme.css

You can get the exact URL for any file in the repo by opening it on GitHub and clicking the Raw button, or by running:

themecmd.cmd png-url "Your Name Themes\Your Theme\your-theme.css"

Preview Images

To include a preview screenshot in the README, add a .png image inside your theme's subfolder:

Your Name Themes/
└── Cool Theme/
    ├── cool-theme.css
    └── preview.png        ← will be picked up automatically

---

Submitting a Theme

1. Fork the repository on GitHub
2. Create your folder under the root if it doesn't exist yet — e.g. Your Name Themes/
3. Add your theme inside a subfolder with its .css file and optional preview image
4. Do not edit README.md, theme-authors.json, or any files in scripts/ or .github/ — these are managed automatically
5. Open a Pull Request against main

Once your PR is open, the automated system takes over:

• Your changes are validated against the rules below
• If everything passes and you are a collaborator, the PR is auto-merged within seconds
• The README updates itself automatically after merge

---

Auto-Merge Rules

The repo uses an automated validation system on every pull request. Here is exactly what is and isn't allowed.

What passes automatically

Scenario	Result
Collaborator adds/edits/deletes files in their own folder	Auto-merged
Collaborator adds files to a new, unregistered folder	Auto-merged, folder registered automatically

What gets blocked

Scenario	Reason
Any change to README.md	Auto-generated — edits are overwritten on merge
Any change to theme-authors.json	Managed by the repo owner only
Any change to scripts/, .github/, themecmd.cmd, THEMECMD.md	Protected tooling files
Editing or deleting files in another contributor's folder	Ownership violation
Modifying/deleting files in an unregistered folder	Can't verify ownership
Not a collaborator	Requires manual review by the repo owner

When a PR is blocked, a comment is posted explaining exactly what went wrong and how to fix it.

Not a collaborator?

If you aren't an approved collaborator yet, your PR will be flagged for manual review — it won't be auto-merged or auto-rejected. The repo owner is notified and will review it. Once approved, future PRs from you will auto-merge.

---

themecmd Reference

themecmd.cmd is a Windows command-line tool that wraps the README generation script. Run it from the repo root.

Commands

themecmd.cmd

Generates README.md from all theme metadata. Prompts for author info if any is missing.

themecmd.cmd -NoAuthorPrompt

Generates README without prompting — uses existing metadata only.

themecmd.cmd doctor

Runs a health check across all theme folders. Reports PASS, WARN, or FAIL for each theme.

themecmd.cmd png-url "Silver Themes\Legoshi\legoshi.png"

Returns the raw.githubusercontent.com URL for an image in the repo. Useful for linking previews.

themecmd.cmd help

Prints all available commands and options.

Exit codes

Code	Meaning
0	Success
1	Failure or invalid command

Notes

• Requires PowerShell (pwsh preferred, falls back to powershell)
• Always run from the repo root, not from inside a subfolder
• The generated README.md should not be committed manually — the CI handles it on merge

---

Common Issues

Error: Path must be inside the repo root You passed an absolute or escaped path to png-url. Use a repo-relative path:

themecmd.cmd png-url "Silver Themes\Legoshi\legoshi.png"

Doctor reports WARN on my theme Your CSS header is missing one or more required fields (@name, @author, @version, @description). Add them and re-run.

My PR was blocked for editing README.md Remove README.md from your PR entirely. It regenerates automatically after merge — any changes you make to it will be overwritten.

My PR was blocked for touching another folder Each contributor owns exactly one folder. Changes to files you did not create are not allowed. If you need to suggest a fix to another theme, open an issue and tag the owner.

I'm not a collaborator and my PR is sitting there This is expected — the repo owner has been notified and will review manually. No action needed on your end.