Skip to content

Developer & Contributor Guide

Jump to bottom
Silverfox0338 edited this page Apr 19, 2026 · 16 revisions

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

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.

Content Policy

All themes submitted to this repo must follow these rules. Violating them can result in your theme being removed and your contributor access being revoked.

NSFW content

Themes containing NSFW content (nudity, sexually explicit imagery, graphic violence, or other mature content) must be clearly labeled in the theme's @name and @description fields. Example:

/**
 * @name My Theme [NSFW]
 * @description A dark theme with mature artwork. Contains NSFW imagery.
 */

Unlabeled NSFW content is grounds for immediate removal and termination from the repo. If you are unsure whether your content qualifies as NSFW, label it anyway — it is always better to over-label than to be removed.

General rules

  • No malicious CSS (keyloggers, crash-on-load exploits, or anything intentionally harmful)
  • No spam, placeholder themes, or clearly unfinished work submitted as complete
  • No impersonating other contributors or theme authors
  • Keep your AUTHOR.md relevant to Discord theming — no unrelated promotions

The repo owner reserves the right to remove any content and revoke contributor access at any time for violations of these policies.

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

This exists for two reasons: external hosts like Imgur are blocked in parts of the EU (Germany and others), which means your theme's background would just be broken for those users. GitHub raw URLs work everywhere. It also protects against external hosts going down or purging images after your theme is merged.

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.

Home · Developer & Contributor Guide · Submit a Theme · Report an Issue · GitHub Repo

discord-themes

Home Developer & Contributor Guide

Getting Started

Submitting a Theme

Rules & Automation

Tooling

GitHub Repo · Open an Issue

Clone this wiki locally