docs: add layouts (@fehmer) (#6461)

Author: fehmer

docs/CONTRIBUTING.md

@@ -8,6 +8,7 @@
   - [Theme Guidelines](#theme-guidelines)
   - [Language Guidelines](#language-guidelines)
   - [Quote Guidelines](#quote-guidelines)
+  - [Layout Guidelines](#layout-guidelines)
 - [Questions](#questions)
 
 ## Getting Started
@@ -54,7 +55,7 @@ Before submitting a theme make sure...
 - your theme has been added to the `_list` file and the `textColor` property is the theme's main color
 - your theme is clear and readable with both `flip test colors` and `colorful mode` enabled and disabled
 
-(If you want to contribute themes but don't know how, check [THEMES.md](./THEMES.md))
+If you want to contribute themes but don't know how, check [THEMES.md](./THEMES.md) 
 
 ### Language Guidelines
 
@@ -63,7 +64,7 @@ Before submitting a theme make sure...
 - Be sure to add your language to the `_list` and `_groups` files
 - Make sure the number of words in the file corresponds to the file name (for example: `languageName.json` is 200 words, `languageName_1k.json` is 1000 words, and so on)
 
-(If you want to contribute languages but don't know how, check [LANGUAGES.md](./LANGUAGES.md))
+If you want to contribute languages but don't know how, check [LANGUAGES.md](./LANGUAGES.md)
 
 ### Quote Guidelines
 
@@ -77,7 +78,11 @@ Before submitting a theme make sure...
 - Remember to name your pull request properly. For example, if you are adding new quotes for the language `French`, your pull request should be named `impr(quotes): add French quotes`.
 
 
-(If you want to contribute quotes but don't know how, check [QUOTES.md](./QUOTES.md))
+If you want to contribute quotes but don't know how, check [QUOTES.md](./QUOTES.md)
+
+### Layout Guidelines
+
+If you want to contribute layouts but don't know how, check [LAYOUTS.md](./LAYOUTS.md)
 
 ## Questions
 

docs/LANGUAGES.md

@@ -17,7 +17,7 @@ Once you have forked the repository you can now add your language. Create a new
 
 The contents of the file should be as follows:
 
-```
+```json
 {
   "name": string,
   "rightToLeft": boolean,
@@ -33,7 +33,7 @@ It is recommended that you familiarize yourselves with JSON before adding a lang
 
 In addition to the language file, you need to add your language to the `_groups.json` and `_list.json` files in the same directory. Add the name of the language to the `_groups.json` file like so:
 
-```
+```json
 {
   "name": "spanish",
   "languages": ["spanish", "spanish_1k", "spanish_10k"]
@@ -52,7 +52,7 @@ The `languages` field is the list of files that you have created for your langua
 
 Add your language lists to the `_list.json` file like so:
 
-```
+```json
 ,"spanish"
 ,"spanish_1k"
 ,"spanish_10k"
@@ -74,5 +74,5 @@ Create a pull request:
 
 ## Language Guidelines
 
-Make sure your language follows the language guidelines.
-[Language guidelines](./CONTRIBUTING.md#language-guidelines)
+Make sure your language follows the [Language guidelines](./CONTRIBUTING.md#language-guidelines).
+

docs/LAYOUTS.md

@@ -0,0 +1,72 @@
+### **Table of Contents**
+
+- [Forking Monkeytype](#forking-monkeytype)
+- [Creating Layouts](#creating-layouts  )
+- [Committing Layouts](#committing-layouts)
+
+### Forking Monkeytype
+
+First, you will have to make a personal copy of the Monkeytype repository, also known as "forking". Go to the [Monkeytype repo](https://github.com/monkeytypegame/monkeytype/) and then click the "fork" button.
+
+<img width="1552" alt="Screenshot showing location of the fork button on GitHub." src="https://user-images.githubusercontent.com/83455454/149194972-23343642-7a1f-4c0c-b5f2-36f4b39a2639.png">
+
+## Creating Layouts
+
+Once you have forked the repository you can now add your layout. Create a new JSON file in `./frontend/static/layouts/`, named as the layout name, e.g. `qwerty.json`.
+
+The contents of the file should be as follows:
+
+```json
+{
+  "keymapShowTopRow": false,
+  "type": "ansi",
+  "keys": {
+    "row1": ["`~", "1!", "2@", "3#", "4$", "5%", "6^", "7&", "8*", "9(", "0)", "-_", "=+"],
+    "row2": ["qQ", "wW", "eE", "rR", "tT", "yY", "uU", "iI", "oO", "pP", "[{", "]}", "\\|"],
+    "row3": ["aA", "sS", "dD", "fF", "gG", "hH", "jJ", "kK", "lL", ";:", "'\""],
+    "row4": ["zZ", "xX", "cC", "vV", "bB", "nN", "mM", ",<", ".>", "/?"],
+    "row5": [" "]
+  }
+}
+
+```
+
+It is recommended that you familiarize yourselves with JSON before adding a layout.
+
+`keymapShowTopRow` indicates whether to always show the first row of the layout.
+`type` can be `ansi` or  `iso`.
+
+In `keys` you need to specify `row1` to  `row5`. Add the keys within the row as string. The string can have up to four character. The character define unshifted, shifted, alt-gr and shifted alt-gr character in this order. For example `eE€` defines `e` on regular key press, `E` if `shift` is held and `€` if `alt-gr` is held.
+
+**Note:**  Quote and backslash characters need to be escaped: `\"` and `\\`.
+
+For ansi layouts the number of keys need to be exactly thirteen for `row1` and `row2`, eleven for `row3`, ten for `row4` and one or two for `row5`.
+
+For iso the number of keys need to be exactly thirteen for `row1`, twelve for `row2` and  `row3`, eleven for `row4` and one or two for `row5`.
+
+
+
+In addition to the layout file you need to add your layout to the `frontend/src/ts/constants/layouts.ts` file. Just append your layout name (without the `.json`) at the __end__ of the array. Remember to add a comma like this:
+
+```ts
+  "ergopti",
+  "sword",
+  "YOUR_LAYOUT",
+];
+``` 
+
+### Committing Layouts
+
+Once you have created your layout, you now need to create a pull request to the main Monkeytype repository. Go to the branch where you created your layout on GitHub. Then make sure your branch is up to date. Once it is up to date, click "contribute".
+
+Update branch:
+<img width="1552" alt="Screenshot showing how to update the fork to match the main Monkeytype repository" src="https://user-images.githubusercontent.com/83455454/149186547-5b9fe4fd-b944-4eed-a959-db43f96198bf.png">
+
+Create a pull request:
+<img width="1552" alt="Screenshot showing how to create a pull request to the main Monkeytype repository" src="https://user-images.githubusercontent.com/83455454/149186637-66dae488-05ae-45c4-9217-65bc36c4927b.png">
+
+Make sure your PR title follow the syntax `feat(layout): add <YOUR_LAYOUT> layout (@<YOUR_GITHUB_NAME>)`, e.g. `feat(layout): add qwerty layout (@teddinotteddy)`
+
+## Layout Guidelines
+
+Make sure your layout follows the [Layout guidelines](./CONTRIBUTING.md#layout-guidelines).

docs/QUOTES.md

@@ -15,7 +15,7 @@ First you will have to copy the Monkeytype repository also known as forking. Go
 
 After you forked the Monkeytype repository you can now add your quotes. (If you haven't already forked the repository, refer to this [section](#forking-monkeytype).) (Before continuing to the next step make sure the quote's language exists in Monkeytype) Add this code in at the end of the quotes `./frontend/static/quotes/[language].json`:
 
-```
+```json
 {
     "text": "[quote]",
     "source": "[source]",
@@ -24,7 +24,7 @@ After you forked the Monkeytype repository you can now add your quotes. (If you
 }
 ```
 
-(If the language does exist in Monkeytype, but there are no quotes for it create a new file for the language)
+If the language does exist in Monkeytype, but there are no quotes for it create a new file for the language.
 
 ### Committing Quotes
 
@@ -38,5 +38,5 @@ Create a pull request:
 
 ## Quote Guidelines
 
-Make sure your quote(s) follows the quote guidelines.
-[Quote guidelines](./CONTRIBUTING.md#quote-guidelines)
+Make sure your quote(s) follows the [Quote guidelines](./CONTRIBUTING.md#quote-guidelines).
+

docs/THEMES.md

@@ -18,7 +18,7 @@ After you have forked the repository you can now add your theme. Create a CSS fi
 
 Then add this code to your file:
 
-```
+```css
 :root {
     --bg-color: #ffffff;
     --main-color: #ffffff;
@@ -38,7 +38,7 @@ Here is an image showing what all the properties correspond to:
 
 Change the corresponding hex codes to create your theme. Then, go to `./frontend/static/themes/_list.json` and add the following code to the very end of the file (inside the square brackets):
 
-```
+```json
   {
     "name": "theme_name",
     "bgColor": "#ffffff",
@@ -64,5 +64,5 @@ Add some screenshots of your theme to the pull request. Click "create pull reque
 
 ## Theme Guidelines
 
-Make sure your theme follows the theme guidelines.
-[Theme guidelines](./CONTRIBUTING.md#theme-guidelines)
+Make sure your theme follows the [Theme guidelines](./CONTRIBUTING.md#theme-guidelines).
+