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
• AUTHOR.md — Your Profile Page
• 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 and your optional profile file live inside it.

discord-themes/
├── Silver Themes/              ← contributor folder
│   ├── AUTHOR.md               ← optional profile file (must be this exact name)
│   └── My Theme/               ← theme subfolder (one per theme)
│       ├── my-theme.css        ← theme CSS (required)
│       ├── preview.png         ← preview image (optional)
│       └── preview.gif         ← animated preview (optional)
└── Your Name Themes/
    ├── AUTHOR.md
    └── Cool Theme/
        └── cool-theme.css

Rules at a glance:

File	Where it goes	Notes
.css	Inside a theme subfolder	Never directly in your contributor folder root
AUTHOR.md	Directly in your contributor folder root	Must be this exact name, one per folder
.png .gif .jpg .webp .svg	Inside a theme subfolder	Not at your contributor folder root
Any other type	Not allowed	Contact the repo owner if you need an exception

---

Theme File Format

Every theme must be a .css file with a metadata header block at the top. This block drives the README and the doctor check.

/**
 * @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 entry in theme-authors.json
@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 to warn.

Raw URL

Users install themes via the raw GitHub URL — no downloading required. Once your theme is merged, the URL will be:

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

Get the exact URL for any file using:

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

Preview Images

Add a .png, .gif, or .jpg inside your theme's subfolder to include a preview in the README:

Your Name Themes/
└── Cool Theme/
    ├── cool-theme.css
    └── preview.png

Image Hosting Requirements

All images referenced inside your CSS must be hosted in this GitHub repository. External image hosts are not allowed.

Host	Allowed
raw.githubusercontent.com/Silverfox0338/discord-themes/…	Yes
Imgur, Discord CDN, personal servers, or any other external host	No

How to host an image here:

1. Place the image file inside your theme subfolder (e.g. Your Name Themes/Cool Theme/bg.png)
2. Get the raw URL with:

   .\themecmd.cmd png-url "Your Name Themes\Cool Theme\bg.png"

3. Use that URL in your CSS:

   --background-image: url("https://raw.githubusercontent.com/Silverfox0338/discord-themes/main/Your%20Name%20Themes/Cool%20Theme/bg.png");

PRs containing external image URLs in CSS will be automatically blocked and the offending URLs will be reported. If you don't use any background images, you don't need to add any image files at all — that's fine.

---

AUTHOR.md — Your Profile Page

You can include an AUTHOR.md file directly in your contributor folder root. This is completely optional but encouraged.

What to include:

• A short bio or introduction
• Links to your other Discord themes or related work
• Links to your personal site, portfolio, or social profiles (Discord theme community related)
• Any shoutouts — just keep the repo in mind and consider linking back to it

What to keep in mind:

• Keep it relevant — this isn't a general social media profile
• Only promote work that's related to Discord theming or design
• No spam, no unrelated content
• The file must be named exactly AUTHOR.md — any other name will be flagged by the doctor and blocked in PRs

Example:

# 8Bit

Discord theme designer. I make anime-inspired themes for BetterDiscord and Vencord.

## My Themes
- [Dr. Stone](https://raw.githubusercontent.com/Silverfox0338/discord-themes/main/8Bit%20Themes/Dr.%20Stone/dr.stone.css)
- [Hello World](https://raw.githubusercontent.com/Silverfox0338/discord-themes/main/8Bit%20Themes/Hello%20World/Hello%20World.css)

## Links
- [GitHub](https://github.com/8-bitStudio)

---

Submitting a Theme

1. Fork the repository on GitHub
2. Create your folder if it doesn't exist — e.g. Your Name Themes/
3. Create a theme subfolder — e.g. Your Name Themes/My Theme/
4. Add your .css file inside the theme subfolder with a valid metadata header
5. Optionally add a preview image and/or an AUTHOR.md in your contributor folder root
6. Do not edit README.md, theme-authors.json, or anything in scripts/ or .github/ — these are managed automatically
7. Open a Pull Request against main

Once your PR is open, the automated system validates it. If you are a collaborator and everything passes, it auto-merges within seconds and the README updates itself.

---

Auto-Merge Rules

The repo validates every pull request automatically.

What passes

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
README.md modified	Auto-generated — edits are overwritten on merge
theme-authors.json, scripts/, .github/ modified	Protected files, owner-only
Editing another contributor's folder	Ownership violation
.css file directly in contributor folder root	Must be inside a theme subfolder
.md file inside a theme subfolder	Must be at contributor folder root only
.md file not named AUTHOR.md	Must use the exact filename AUTHOR.md
Images or other files at contributor folder root	Must be inside a theme subfolder
Unsupported file type (anything not .css, .md, .png, .gif, .jpg, .jpeg, .webp, .svg)	Not allowed
Not a collaborator	Flagged for manual review

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

---

themecmd Reference

themecmd.cmd is a Windows command-line tool for README generation and health checks. Run it from the repo root.

Note: From PowerShell, prefix commands with .\ — e.g. .\themecmd.cmd. From Command Prompt, the prefix is not needed.

Commands

Generate README (default):

.\themecmd.cmd
.\themecmd.cmd -NoAuthorPrompt
.\themecmd.cmd generatereadme -NoAuthorPrompt
.\themecmd.cmd generatereadme -OutputPath "README.md" -MetadataPath "theme-authors.json"

Run doctor (full repo):

.\themecmd.cmd doctor

Checks all theme folders for valid CSS metadata headers, AUTHOR.md naming, and theme-authors.json consistency. Reports PASS, WARN, or FAIL.

Run doctor (scoped to one folder):

.\themecmd.cmd doctor "Silver Themes"
.\themecmd.cmd doctor "8Bit Themes"

Runs the same checks but only for the specified contributor folder. Useful when you only want to validate your own work.

Scaffold a new theme (interactive):

.\themecmd.cmd new-theme

Walks you through creating a new CSS file with the correct metadata header. Prompts for name, author, version, description, and target folder — then generates a complete starter template with color variables, background properties, and font settings already wired up.

Scaffold a new theme (non-interactive):

.\themecmd.cmd new-theme -Name "My Theme" -Author "YourName" -Folder "Your Name Themes"
.\themecmd.cmd new-theme -Name "My Theme" -Author "YourName" -Version "1.0.0" -Description "A cool theme" -Folder "Your Name Themes" -FileName "my-theme.css"

Any omitted parameters fall back to the interactive prompts. Useful for scripting or when you already know all the values.

Note: The generated template includes url("https://i.imgur.com/YOUR_IMAGE.jpg") as a placeholder. You must replace this with a raw GitHub URL before submitting — external image URLs will be blocked in PR validation.

Get raw URL for a file:

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

Returns the raw.githubusercontent.com URL. Works for any file in the repo, not just images — use it to get the install URL for your CSS file too.

Help:

.\themecmd.cmd help

Exit codes

Code	Meaning
0	Success
1	Failure or invalid command

---

Common Issues

Error: Path must be inside the repo root Use a path relative to the repo root, not an absolute 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. Also check if your AUTHOR.md is empty or misnamed.

Doctor reports WARN about AUTHOR.md Either your markdown file isn't named exactly AUTHOR.md (rename it) or it exists but is empty (add some content).

My PR was blocked for a file structure issue See the Auto-Merge Rules table above. The most common causes:

• CSS placed directly in your contributor folder instead of a theme subfolder
• A .md file named something other than AUTHOR.md
• An image placed at your contributor folder root instead of inside a theme subfolder

My PR was blocked for editing README.md Remove README.md from your PR entirely — it regenerates automatically on merge.

My PR was blocked for touching another folder Each contributor owns exactly one folder. If you want to suggest a change to another theme, open an issue and tag the folder owner.

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