Basic Contributions

Add languages, quotes, and themes to Monkeytype without setting up a local development environment

This guide covers how to make basic contributions to Monkeytype purely through GitHub’s web interface. You won’t need to set up a local development environment - just a browser and a GitHub account.

Use this guide for:

• Adding or updating languages
• Contributing quotes
• Creating themes
• Fixing translations

For code changes that affect functionality, see Advanced Contributions.

Prerequisites

All you need is:

• A browser that can access GitHub
• A GitHub account (create one if needed)

Watch this YouTube tutorial for a visual walkthrough of the basic contribution process.

Forking Monkeytype

1. Create Your Fork

   Click here to fork Monkeytype or navigate to the repository and click the Fork button in the top-right corner.

   This creates your own copy of the repository under your GitHub account.

2. Navigate to Your Fork

   Go to your GitHub profile and find the monkeytype repository under your repositories.

Making Changes

There are two ways to edit files in your fork:

Option 1: VS Code Web Editor (Recommended)

The VS Code web editor makes it easier to edit multiple files and work with complex changes.

1. Open Web Editor

   In your fork, go to the Code tab and press the . (period/dot) key. This opens an online VS Code instance in your browser.

2. Make Your Changes

   Edit the files you need to change using the file explorer on the left.

3. Stage and Commit

   1. Open the Source Control tab with Ctrl/Cmd + Shift + G
   2. Click the + next to changed files to stage them
   3. Type a brief commit message describing your changes
   4. Press Ctrl/Cmd + Enter to commit

Option 2: GitHub Web UI

For simple, single-file edits, you can use GitHub’s built-in editor.

1. Navigate to File

   Browse to the file you want to edit in your forked repository.

2. Click Edit

   Click the pencil icon on the right side of the file view.

   Very large files may not have an edit option. In these cases, use the VS Code web editor or set up a local development environment.

3. Make Changes

   Edit the file content as needed.

4. Commit Changes

   1. Scroll to the bottom of the page
   2. Add a descriptive commit title
   3. (Optional) Add a detailed description
   4. Select “Commit directly to your current branch”
   5. Click Commit changes

Adding Languages

1. Create the Language File

   Navigate to frontend/static/languages/ in your fork.

   Create a new JSON file named according to the word count:

   • Less than 1,000 words: language_name.json
   • 1,000+ words: language_name_1k.json
   • 10,000+ words: language_name_10k.json

   Minimum of 200 words required.

2. Add Language Data

   Use this structure:

   {
     "name": "Language Name",
     "rightToLeft": false,
     "ligatures": false,
     "orderedByFrequency": true,
     "bcp47": "en-US",
     "words": [
       "word1",
       "word2",
       "word3"
     ]
   }
   

   • rightToLeft: Set to true for RTL languages (Arabic, Hebrew, etc.)
   • ligatures: Set to true if letters join together (Arabic, Malayalam, etc.)
   • orderedByFrequency: Set to true if words are sorted by frequency
   • bcp47: The IETF language tag
3. Update the Language Schema

   Go to packages/schemas/src/languages.ts and add your language name(s) to the end of the LanguageSchema enum:

   export const LanguageSchema = z.enum([
     "english",
     "english_1k",
     // ... existing languages
     "your_language",
     "your_language_1k",
   ]);
   
4. Add to Language Groups

   Go to frontend/src/ts/constants/language.ts and add your language to the LanguageGroups map:

   export const LanguageGroups: Record<string, Language[]> = {
     // ... existing groups
     your_language: [
       "your_language",
       "your_language_1k",
     ]
   };
   

Adding Quotes

1. Navigate to Quotes File

   Go to frontend/static/quotes/[language].json for your target language.

   If the file doesn’t exist, create it.

2. Add Your Quote

   Add this structure at the end of the quotes array:

   {
     "text": "Your quote text here",
     "source": "Author or Source",
     "id": 123,
     "length": 45
   }
   

   • id: Increment from the last quote’s ID
   • length: Character count of the quote text
   • Minimum quote length: 60 characters
3. Verify Your Quote

   Check that:

   • The quote isn’t a duplicate
   • The length value is accurate
   • The id is correctly incremented
   • No trailing commas in the JSON

For quotes in non-English languages, include translations in your pull request description to help with verification.

Creating Themes

1. Choose a Theme Name

   Pick a name that is:

   • All lowercase
   • Uses underscores instead of spaces
   • Example: my_awesome_theme
2. Add to Theme Schema

   Go to packages/schemas/src/themes.ts and add your theme name to the end of ThemeNameSchema:

   export const ThemeNameSchema = z.enum([
     "8008",
     "80s_after_dark",
     // ... existing themes
     "your_theme_name",
   ]);
   
3. Define Theme Colors

   Go to frontend/src/ts/constants/themes.ts and add your theme configuration at the end:

   export const themes: Record<ThemeName, Theme> = {
     // ... existing themes
     your_theme_name: {
       bg: "#323437",
       caret: "#e2b714",
       main: "#e2b714",
       sub: "#646669",
       subAlt: "#2c2e31",
       text: "#d1d0c5",
       error: "#ca4754",
       errorExtra: "#7e2a33",
       colorfulError: "#ca4754",
       colorfulErrorExtra: "#7e2a33",
     },
   };
   

   Color properties:

   • bg: Background color
   • caret: Typing cursor color
   • main: Primary accent color
   • sub: Secondary text color
   • subAlt: Alternative background color
   • text: Main text color
   • error: Error text color
   • errorExtra: Error background color
   • colorfulError: Colorful mode error text
   • colorfulErrorExtra: Colorful mode error background
4. Add Custom CSS (Optional)

   If your theme needs custom styling:

   1. Create frontend/static/themes/your_theme_name.css
   2. Add hasCss: true to your theme configuration:

   your_theme_name: {
     // ... color properties
     hasCss: true,
   },
   

Creating a Pull Request

1. Update Your Fork

   Go to your fork’s main page and click the “Sync fork” or “Update branch” button to sync with the latest changes from the main repository.

2. Open Pull Request

   Click the Contribute button, then Open pull request.

3. Fill in Details

   • Verify the base repository is monkeytypegame/monkeytype and base branch is master
   • Add a descriptive title following the naming guidelines
   • Describe your changes in detail
   • For themes, include screenshots
   • For non-English quotes, include translations
4. Submit

   Click Create pull request to submit your contribution.

After Submission

Once your pull request is created:

1. Wait for maintainer review
2. Respond to any feedback or change requests
3. Make additional commits to your branch if needed
4. Once approved, a maintainer will merge your contribution

Guidelines

Make sure your contribution follows the appropriate guidelines:

• Theme Guidelines
• Language Guidelines
• Quote Guidelines

Getting Help

If you need assistance:

• Join the #development channel on Discord
• Ask on GitHub Discussions
• Email the maintainers at [e-mail]