Merge remote-tracking branch 'origin/master' into develop

docs/cli_commands.md

@@ -254,15 +254,21 @@ qmk doctor [-y] [-n]
 
 Check your environment for problems and prompt to fix them:
 
-    qmk doctor
+```
+qmk doctor
+```
 
 Check your environment and automatically fix any problems found:
 
-    qmk doctor -y
+```
+qmk doctor -y
+```
 
 Check your environment and report problems only:
 
-    qmk doctor -n
+```
+qmk doctor -n
+```
 
 ## `qmk format-json`
 
@@ -290,15 +296,21 @@ This command is directory aware. It will automatically fill in KEYBOARD and/or K
 
 Show basic information for a keyboard:
 
-    qmk info -kb planck/rev5
+```
+qmk info -kb planck/rev5
+```
 
 Show the matrix for a keyboard:
 
-    qmk info -kb ergodox_ez -m
+```
+qmk info -kb ergodox_ez -m
+```
 
 Show a JSON keymap for a keyboard:
 
-    qmk info -kb clueboard/california -km default
+```
+qmk info -kb clueboard/california -km default
+```
 
 ## `qmk json2c`
 
@@ -350,7 +362,9 @@ This command is directory aware. It will automatically fill in KEYBOARD and/or K
 
 Do a basic lint check:
 
-    qmk lint -kb rominronin/katana60/rev2
+```
+qmk lint -kb rominronin/katana60/rev2
+```
 
 ## `qmk list-keyboards`
 
@@ -789,16 +803,22 @@ qmk pytest [-t TEST]
 
 Run entire test suite:
 
-    qmk pytest
+```
+qmk pytest
+```
 
 Run test group:
 
-    qmk pytest -t qmk.tests.test_cli_commands
+```
+qmk pytest -t qmk.tests.test_cli_commands
+```
 
 Run single test:
 
-    qmk pytest -t qmk.tests.test_cli_commands.test_c2json
+```
-    qmk pytest -t qmk.tests.test_qmk_path
+qmk pytest -t qmk.tests.test_cli_commands.test_c2json
+qmk pytest -t qmk.tests.test_qmk_path
+```
 
 ## `qmk painter-convert-graphics`
 
@@ -835,16 +855,24 @@ options:
 
 Run entire test suite:
 
-    qmk test-c
+```
+qmk test-c
+```
 
 List available tests:
 
-    qmk test-c --list
+```
+qmk test-c --list
+```
 
 Run matching test:
 
-    qmk test-c --test unicode*
+```
+qmk test-c --test unicode*
+```
 
 Run single test:
 
-    qmk test-c --test basic
+```
+qmk test-c --test basic
+```

docs/cli_configuration.md

@@ -43,7 +43,9 @@ user.keymap: None -> default
 
 The `qmk config` command is used to interact with the underlying configuration. When run with no argument it shows the current configuration. When arguments are supplied they are assumed to be configuration tokens, which are strings containing no spaces with the following form:
 
-    <subcommand|general|default>[.<key>][=<value>]
+```
+<subcommand|general|default>[.<key>][=<value>]
+```
 
 ## Setting Configuration Values
 
@@ -63,19 +65,27 @@ You can read configuration values for the entire configuration, a single key, or
 
 ### Entire Configuration Example
 
-    qmk config
+```
+qmk config
+```
 
 ### Whole Section Example
 
-    qmk config compile
+```
+qmk config compile
+```
 
 ### Single Key Example
 
-    qmk config compile.keyboard
+```
+qmk config compile.keyboard
+```
 
 ### Multiple Keys Example
 
-    qmk config user compile.keyboard compile.keymap
+```
+qmk config user compile.keyboard compile.keymap
+```
 
 ## Deleting Configuration Values
 

docs/cli_development.md

@@ -192,11 +192,15 @@ We use nose2, flake8, and yapf to test, lint, and format code. You can use the `
 
 ### Testing and Linting
 
-    qmk pytest
+```
+qmk pytest
+```
 
 ### Formatting
 
-    qmk format-python
+```
+qmk format-python
+```
 
 ## Formatting Details
 
@@ -212,7 +216,9 @@ Our tests can be found in `lib/python/qmk/tests/`. You will find both unit and i
 
 If your PR does not include a comprehensive set of tests please add comments like this to your code so that other people know where they can help:
 
+```python
     # TODO(unassigned/<your_github_username>): Write <unit|integration> tests
+```
 
 We use [nose2](https://nose2.readthedocs.io/en/latest/getting_started.html) to run our tests. You can refer to the nose2 documentation for more details on what you can do in your test functions.
 

docs/cli_tab_complete.md

@@ -10,22 +10,30 @@ There are several ways you can setup tab completion.
 
 Add this to the end of your `.profile` or `.bashrc`:
 
-    source ~/qmk_firmware/util/qmk_tab_complete.sh
+```
+source ~/qmk_firmware/util/qmk_tab_complete.sh
+```
 
 If you put `qmk_firmware` into another location you will need to adjust this path.
 
 Zsh users will need to load `bashcompinit`. The following can be added to `~/.zshrc` file:
 
-    autoload -Uz bashcompinit && bashcompinit
+```
+autoload -Uz bashcompinit && bashcompinit
+```
 
 ### System Wide Symlink
 
 If you want the tab completion available to all users of the system you can add a symlink to the `qmk_tab_complete.sh` script:
 
-    ln -s ~/qmk_firmware/util/qmk_tab_complete.sh /etc/profile.d/qmk_tab_complete.sh
+```
+ln -s ~/qmk_firmware/util/qmk_tab_complete.sh /etc/profile.d/qmk_tab_complete.sh
+```
 
 ### System Wide Copy
 
 In some cases a symlink may not work. Instead you can copy the file directly into place. Be aware that updates to the tab complete script may happen from time to time, you will want to recopy the file periodically.
 
-    cp util/qmk_tab_complete.sh /etc/profile.d
+```
+cp util/qmk_tab_complete.sh /etc/profile.d
+```

docs/feature_audio.md

@@ -263,31 +263,39 @@ In music mode, the following keycodes work differently, and don't pass through:
 
 The pitch standard (`PITCH_STANDARD_A`) is 440.0f by default - to change this, add something like this to your `config.h`:
 
-    #define PITCH_STANDARD_A 432.0f
+```c
+#define PITCH_STANDARD_A 432.0f
+```
 
 You can completely disable Music Mode as well. This is useful, if you're pressed for space on your controller.  To disable it, add this to your `config.h`:
 
-    #define NO_MUSIC_MODE
+```c
+#define NO_MUSIC_MODE
+```
 
 ### Music Mask
 
 By default, `MUSIC_MASK` is set to `keycode < 0xFF` which means keycodes less than `0xFF` are turned into notes, and don't output anything. You can change this by defining this in your `config.h` like this:
 
-    #define MUSIC_MASK keycode != KC_NO
+```c
+#define MUSIC_MASK keycode != KC_NO
+```
 
 Which will capture all keycodes - be careful, this will get you stuck in music mode until you restart your keyboard!
 
 For a more advanced way to control which keycodes should still be processed, you can use `music_mask_kb(keycode)` in `<keyboard>.c` and `music_mask_user(keycode)` in your `keymap.c`:
 
-    bool music_mask_user(uint16_t keycode) {
+```c
-      switch (keycode) {
+  bool music_mask_user(uint16_t keycode) {
-        case RAISE:
+    switch (keycode) {
-        case LOWER:
+      case RAISE:
-          return false;
+      case LOWER:
-        default:
+        return false;
-          return true;
+      default:
-      }
+        return true;
     }
+  }
+```
 
 Things that return false are not part of the mask, and are always processed.
 
@@ -329,8 +337,9 @@ Keycodes available:
 
 The feature is disabled by default, to save space.  To enable it, add this to your `config.h`:
 
-    #define AUDIO_CLICKY
+```c
-
+#define AUDIO_CLICKY
+```
 
 You can configure the default, min and max frequencies, the stepping and built in randomness by defining these values: 
 
@@ -343,9 +352,6 @@ You can configure the default, min and max frequencies, the stepping and built i
 | `AUDIO_CLICKY_FREQ_RANDOMNESS`     |  0.05f |  Sets a factor of randomness for the clicks, Setting this to `0f` will make each click identical, and `1.0f` will make this sound much like the 90's computer screen scrolling/typing effect. | 
 | `AUDIO_CLICKY_DELAY_DURATION` | 1 | An integer note duration where 1 is 1/16th of the tempo, or a sixty-fourth note (see `quantum/audio/musical_notes.h` for implementation details). The main clicky effect will be delayed by this duration.  Adjusting this to values around 6-12 will help compensate for loud switches. |
 
-
-
-
 ## MIDI Functionality
 
 See [MIDI](feature_midi)

docs/feature_auto_shift.md

@@ -51,7 +51,9 @@ Yes, unfortunately.
 
 Add to your `rules.mk` in the keymap folder:
 
-    AUTO_SHIFT_ENABLE = yes
+```
+AUTO_SHIFT_ENABLE = yes
+```
 
 If no `rules.mk` exists, you can create one.
 
@@ -372,22 +374,24 @@ completely normal and with no intention of shifted keys.
 
 #### An Example Run
 
-    hello world. my name is john doe. i am a computer programmer playing with
+```
-    keyboards right now.
+hello world. my name is john doe. i am a computer programmer playing with
+keyboards right now.
 
-    [PRESS AS_DOWN quite a few times]
+[PRESS AS_DOWN quite a few times]
 
-    heLLo woRLd. mY nAMe is JOHn dOE. i AM A compUTeR proGRaMMER PlAYiNG witH
+heLLo woRLd. mY nAMe is JOHn dOE. i AM A compUTeR proGRaMMER PlAYiNG witH
-    KEYboArDS RiGHT NOw.
+KEYboArDS RiGHT NOw.
 
-    [PRESS AS_UP a few times]
+[PRESS AS_UP a few times]
 
-    hello world. my name is john Doe. i am a computer programmer playing with
+hello world. my name is john Doe. i am a computer programmer playing with
-    keyboarDs right now.
+keyboarDs right now.
 
-    [PRESS AS_RPT]
+[PRESS AS_RPT]
 
-    115
+115
+```
 
 The keyboard typed `115` which represents your current `AUTO_SHIFT_TIMEOUT`
 value. You are now set! Practice on the *D* key a little bit that showed up

docs/feature_layouts.md

@@ -37,17 +37,23 @@ New names should try to stick to the standards set by existing layouts, and can
 
 For a keyboard to support a layout, the variable must be defined in it's `<keyboard>.h`, and match the number of arguments/keys (and preferably the physical layout):
 
-    #define LAYOUT_60_ansi KEYMAP_ANSI
+```c
+#define LAYOUT_60_ansi KEYMAP_ANSI
+```
 
 The name of the layout must match this regex: `[a-z0-9_]+`
 
 The folder name must be added to the keyboard's `rules.mk`:
 
-    LAYOUTS = 60_ansi
+```
+LAYOUTS = 60_ansi
+```
 
 `LAYOUTS` can be set in any keyboard folder level's `rules.mk`:
 
-    LAYOUTS = 60_iso
+```
+LAYOUTS = 60_iso
+```
 
 but the `LAYOUT_<layout>` variable must be defined in `<folder>.h` as well.
 
@@ -55,12 +61,16 @@ but the `LAYOUT_<layout>` variable must be defined in `<folder>.h` as well.
 
 You should be able to build the keyboard keymap with a command in this format:
 
-    make <keyboard>:<layout>
+```
+make <keyboard>:<layout>
+```
 
 ### Conflicting layouts
 When a keyboard supports multiple layout options,
 
-    LAYOUTS = ortho_4x4 ortho_4x12
+```
+LAYOUTS = ortho_4x4 ortho_4x12
+```
 
 And a layout exists for both options,
 ```
@@ -77,8 +87,10 @@ layouts/
 
 The FORCE_LAYOUT argument can be used to specify which layout to build
 
-    make <keyboard>:<layout> FORCE_LAYOUT=ortho_4x4
+```
-    make <keyboard>:<layout> FORCE_LAYOUT=ortho_4x12
+make <keyboard>:<layout> FORCE_LAYOUT=ortho_4x4
+make <keyboard>:<layout> FORCE_LAYOUT=ortho_4x12
+```
 
 ## Tips for Making Layouts Keyboard-Agnostic
 
@@ -86,7 +98,9 @@ The FORCE_LAYOUT argument can be used to specify which layout to build
 
 Instead of using `#include "planck.h"`, you can use this line to include whatever `<keyboard>.h` (`<folder>.h` should not be included here) file that is being compiled:
 
-    #include QMK_KEYBOARD_H
+```c
+#include QMK_KEYBOARD_H
+```
 
 If you want to keep some keyboard-specific code, you can use these variables to escape it with an `#ifdef` statement:
 

docs/feature_macros.md

@@ -252,11 +252,15 @@ You can send arbitrary keycodes by wrapping them in:
 
 For example:
 
-    SEND_STRING(SS_TAP(X_HOME));
+```c
+SEND_STRING(SS_TAP(X_HOME));
+```
 
 Would tap `KC_HOME` - note how the prefix is now `X_`, and not `KC_`. You can also combine this with other strings, like this:
 
-    SEND_STRING("VE"SS_TAP(X_HOME)"LO");
+```c
+SEND_STRING("VE"SS_TAP(X_HOME)"LO");
+```
 
 Which would send "VE" followed by a `KC_HOME` tap, and "LO" (spelling "LOVE" if on a newline).
 
@@ -266,7 +270,9 @@ Delays can be also added to the string:
 
 For example:
 
-    SEND_STRING("VE" SS_DELAY(1000) SS_TAP(X_HOME) "LO");
+```c
+SEND_STRING("VE" SS_DELAY(1000) SS_TAP(X_HOME) "LO");
+```
 
 Which would send "VE" followed by a 1-second delay, then a `KC_HOME` tap, and "LO" (spelling "LOVE" if on a newline, but delayed in the middle).
 
@@ -284,7 +290,9 @@ There's also a couple of mod shortcuts you can use:
 These press the respective modifier, send the supplied string and then release the modifier.
 They can be used like this:
 
-    SEND_STRING(SS_LCTL("a"));
+```c
+SEND_STRING(SS_LCTL("a"));
+```
 
 Which would send Left Control+`a` (Left Control down, `a`, Left Control up) - notice that they take strings (eg `"k"`), and not the `X_K` keycodes.
 

docs/flashing_bootloadhid.md

@@ -19,7 +19,9 @@ Using the QMK installation script, detailed [here](newbs_getting_started), the r
 
 To flash via the command line, use the target `:bootloadhid` by executing the following command:
 
-    make <keyboard>:<keymap>:bootloadhid
+```
+make <keyboard>:<keymap>:bootloadhid
+```
 
 ## GUI Flashing
 

docs/hand_wire.md

@@ -181,7 +181,9 @@ Go through the rest of the tabs, assigning keys until you get to the last one wh
 
 The source given by Keyboard Firmware Builder is QMK, but is based on a version of QMK from early 2017. To compile the firmware in a modern version of QMK Firmware, you'll need to export via the `Save Configuration` button, then run:
 
-    qmk import-kbfirmware /path/to/export.json
+```
+qmk import-kbfirmware /path/to/export.json
+```
 
 For example:
 

docs/hardware_keyboard_guidelines.md

@@ -40,7 +40,9 @@ Valid Examples:
 
 QMK uses sub-folders both for organization and to share code between revisions of the same keyboard. You can nest folders up to 4 levels deep:
 
-    qmk_firmware/keyboards/top_folder/sub_1/sub_2/sub_3/sub_4
+```
+qmk_firmware/keyboards/top_folder/sub_1/sub_2/sub_3/sub_4
+```
 
 If a sub-folder has a `rules.mk` file it will be considered a compilable keyboard. It will be available in QMK Configurator and tested with `make all`. If you are using a folder to organize several keyboards from the same maker you should not have a `rules.mk` file.
 
@@ -250,15 +252,21 @@ When developing your keyboard, keep in mind that all warnings will be treated as
 
 If you're adapting your keyboard's setup from another project, but not using the same code, be sure to update the copyright header at the top of the files to show your name, in this format:
 
-    Copyright 2017 Your Name <your@email.com>
+```c
+Copyright 2017 Your Name <your@email.com>
+```
 
 If you are modifying someone else's code and have made only trivial changes you should leave their name in the copyright statement. If you have done significant work on the file you should add your name to theirs, like so:
 
-    Copyright 2017 Their Name <original_author@example.com> Your Name <you@example.com>
+```c
+Copyright 2017 Their Name <original_author@example.com> Your Name <you@example.com>
+```
 
 The year should be the first year the file is created. If work was done to that file in later years you can reflect that by appending the second year to the first, like so:
 
-    Copyright 2015-2017 Your Name <you@example.com>
+```c
+Copyright 2015-2017 Your Name <you@example.com>
+```
 
 ## License
 

docs/how_a_matrix_works.md

@@ -6,6 +6,7 @@ When the circuit is arranged in rows and columns, if a key is pressed, a column
 
 The microcontroller will be set up via the firmware to send a logical 1 to the columns, one at a time, and read from the rows, all at once - this process is called matrix scanning. The matrix is a bunch of open switches that, by default, don't allow any current to pass through - the firmware will read this as no keys being pressed. As soon as you press one key down, the logical 1 that was coming from the column the keyswitch is attached to gets passed through the switch and to the corresponding row - check out the following 2x2 example:
 
+```
         Column 0 being scanned     Column 1 being scanned
                   x                                   x
                  col0     col1              col0     col1
@@ -13,11 +14,13 @@ The microcontroller will be set up via the firmware to send a logical 1 to the c
         row0 ---(key0)---(key1)    row0 ---(key0)---(key1)
                   |        |                 |        |
         row1 ---(key2)---(key3)    row1 ---(key2)---(key3)
+```
 
 The `x` represents that the column/row associated has a value of 1, or is HIGH. Here, we see that no keys are being pressed, so no rows get an `x`. For one keyswitch, keep in mind that one side of the contacts is connected to its row, and the other, its column.
 
 When we press `key0`, `col0` gets connected to `row0`, so the values that the firmware receives for that row is `0b01` (the `0b` here means that this is a bit value, meaning all of the following digits are bits - 0 or 1 - and represent the keys in that column). We'll use this notation to show when a keyswitch has been pressed, to show that the column and row are being connected:
 
+```
         Column 0 being scanned     Column 1 being scanned
                   x                                   x
                  col0     col1              col0     col1
@@ -25,16 +28,20 @@ When we press `key0`, `col0` gets connected to `row0`, so the values that the fi
       x row0 ---(-+-0)---(key1)    row0 ---(-+-0)---(key1)
                   |        |                 |        |
         row1 ---(key2)---(key3)    row1 ---(key2)---(key3)
+```
 
 We can now see that `row0` has an `x`, so has the value of 1. As a whole, the data the firmware receives when `key0` is pressed is:
 
-    col0: 0b01
+```
-    col1: 0b00
+col0: 0b01
-            │└row0
+col1: 0b00
-            └row1
+        │└row0
+        └row1
+```
 
 A problem arises when you start pressing more than one key at a time. Looking at our matrix again, it should become pretty obvious:
 
+```
         Column 0 being scanned     Column 1 being scanned
                   x                                   x
                  col0     col1              col0     col1
@@ -44,16 +51,20 @@ A problem arises when you start pressing more than one key at a time. Looking at
       x row1 ---(key2)---(-+-3)  x row1 ---(key2)---(-+-3)
 
       Remember that this ^ is still connected to row1
+```
 
 The data we get from that is:
 
-    col0: 0b11
+```
-    col1: 0b11
+col0: 0b11
-            │└row0
+col1: 0b11
-            └row1
+        │└row0
+        └row1
+```
 
 Which isn't accurate, since we only have 3 keys pressed down, not all 4. This behavior is called ghosting, and only happens in odd scenarios like this, but can be much more common on a bigger keyboard. The way we can get around this is by placing a diode after the keyswitch, but before it connects to its row. A diode only allows current to pass through one way, which will protect our other columns/rows from being activated in the previous example. We'll represent a dioded matrix like this;
 
+```
         Column 0 being scanned     Column 1 being scanned
                     x                                   x
                   col0      col1              col0     col1
@@ -65,11 +76,13 @@ Which isn't accurate, since we only have 3 keys pressed down, not all 4. This be
                  (key2)   (key3)            (key2)   (key3)
                   !        !                 !        !
         row1 ─────┴────────┘       row1 ─────┴────────┘
+```
 
 In practical applications, the black line of the diode will be placed facing the row, and away from the keyswitch - the `!` in this case is the diode, where the gap represents the black line. A good way to remember this is to think of this symbol: `>|`
 
 Now when we press the three keys, invoking what would be a ghosting scenario:
 
+```
         Column 0 being scanned     Column 1 being scanned
                     x                                   x
                   col0      col1              col0     col1
@@ -81,13 +94,16 @@ Now when we press the three keys, invoking what would be a ghosting scenario:
                  (key2)   (┌─┘3)            (key2)   (┌─┘3)
                   !        !                 !        !
         row1 ─────┴────────┘     x row1 ─────┴────────┘
+```
 
 Things act as they should! Which will get us the following data:
 
-    col0: 0b01
+```
-    col1: 0b11
+col0: 0b01
-            │└row0
+col1: 0b11
-            └row1
+        │└row0
+        └row1
+```
 
 The firmware can then use this correct data to detect what it should do, and eventually, what signals it needs to send to the OS.
 

docs/keymap.md

@@ -10,20 +10,21 @@ For trivial key definitions, the higher 8 bits of the **action code** are all 0
 
 Respective layers can be validated simultaneously. Layers are indexed with 0 to 31 and higher layer has precedence.
 
-    Keymap: 32 Layers                   Layer: action code matrix
+```
-    -----------------                   ---------------------
+Keymap: 32 Layers                   Layer: action code matrix
-    stack of layers                     array_of_action_code[row][column]
+-----------------                   ---------------------
-           ____________ precedence               _______________________
+stack of layers                     array_of_action_code[row][column]
-          /           / | high                  / ESC / F1  / F2  / F3   ....
+       ____________ precedence               _______________________
-      31 /___________// |                      /-----/-----/-----/-----
+      /           / | high                  / ESC / F1  / F2  / F3   ....
-      30 /___________// |                     / TAB /  Q  /  W  /  E   ....
+  31 /___________// |                      /-----/-----/-----/-----
-      29 /___________/  |                    /-----/-----/-----/-----
+  30 /___________// |                     / TAB /  Q  /  W  /  E   ....
-       :   _:_:_:_:_:__ |               :   /LCtrl/  A  /  S  /  D   ....
+  29 /___________/  |                    /-----/-----/-----/-----
-       :  / : : : : : / |               :  /  :     :     :     :
+   :   _:_:_:_:_:__ |               :   /LCtrl/  A  /  S  /  D   ....
-       2 /___________// |               2 `--------------------------
+   :  / : : : : : / |               :  /  :     :     :     :
-       1 /___________// |               1 `--------------------------
+   2 /___________// |               2 `--------------------------
-       0 /___________/  V low           0 `--------------------------
+   1 /___________// |               1 `--------------------------
-
+   0 /___________/  V low           0 `--------------------------
+```
 
 Sometimes, the action code stored in keymap may be referred as keycode in some documents due to the TMK history.
 
@@ -36,50 +37,54 @@ The state of the Keymap layer is determined by two 32 bit parameters:
 
 Keymap layer '0' is usually the `default_layer`, with other layers initially off after booting up the firmware, although this can configured differently in `config.h`. It is useful to change `default_layer` when you completely switch a key layout, for example, if you want to switch to Colemak instead of Qwerty.
 
-    Initial state of Keymap          Change base layout
+```
-    -----------------------          ------------------
+Initial state of Keymap          Change base layout
+-----------------------          ------------------
 
-      31                               31
+  31                               31
-      30                               30
+  30                               30
-      29                               29
+  29                               29
-       :                                :
+   :                                :
-       :                                :   ____________
+   :                                :   ____________
-       2   ____________                 2  /           /
+   2   ____________                 2  /           /
-       1  /           /              ,->1 /___________/
+   1  /           /              ,->1 /___________/
-    ,->0 /___________/               |  0
+,->0 /___________/               |  0
-    |                                |
+|                                |
-    `--- default_layer = 0           `--- default_layer = 1
+`--- default_layer = 0           `--- default_layer = 1
-         layer_state   = 0x00000001       layer_state   = 0x00000002
+     layer_state   = 0x00000001       layer_state   = 0x00000002
+```
 
 On the other hand, you can change `layer_state` to overlay the base layer with other layers for features such as navigation keys, function keys (F1-F12), media keys, and/or special actions.
 
-    Overlay feature layer
+```
-    ---------------------      bit|status
+Overlay feature layer
-           ____________        ---+------
+---------------------      bit|status
-      31  /           /        31 |   0
+       ____________        ---+------
-      30 /___________// -----> 30 |   1
+  31  /           /        31 |   0
-      29 /___________/  -----> 29 |   1
+  30 /___________// -----> 30 |   1
-       :                        : |   :
+  29 /___________/  -----> 29 |   1
-       :   ____________         : |   :
+   :                        : |   :
-       2  /           /         2 |   0
+   :   ____________         : |   :
-    ,->1 /___________/  ----->  1 |   1
+   2  /           /         2 |   0
-    |  0                        0 |   0
+,->1 /___________/  ----->  1 |   1
-    |                                 +
+|  0                        0 |   0
-    `--- default_layer = 1            |
+|                                 +
-         layer_state   = 0x60000002 <-'
+`--- default_layer = 1            |
-
+     layer_state   = 0x60000002 <-'
-
+```
 
 ### Layer Precedence and Transparency
 Note that ***higher layers have higher priority within the stack of layers***. The firmware works its way down from the highest active layers to look up keycodes. Once the firmware locates a keycode other than `KC_TRNS` (transparent) on an active layer, it stops searching, and lower layers aren't referenced.
 
-           ____________
+```
-          /           /  <--- Higher layer
+   ____________
-         /  KC_TRNS  //
+  /           /  <--- Higher layer
-        /___________//   <--- Lower layer (KC_A)
+ /  KC_TRNS  //
-        /___________/
+/___________//   <--- Lower layer (KC_A)
-    
+/___________/
-    In the above scenario, the non-transparent keys on the higher layer would be usable, but whenever `KC_TRNS` (or equivalent) is defined, the keycode (`KC_A`) on the lower level would be used.
+```
+
+In the above scenario, the non-transparent keys on the higher layer would be usable, but whenever `KC_TRNS` (or equivalent) is defined, the keycode (`KC_A`) on the lower level would be used.
 
 **Note:** Valid ways to denote transparency on a given layer:
 * `KC_TRANSPARENT`
@@ -101,27 +106,29 @@ There are 2 main sections of a `keymap.c` file you'll want to concern yourself w
 
 At the top of the file you'll find this:
 
-    #include QMK_KEYBOARD_H
+```c
+#include QMK_KEYBOARD_H
 
-    // Helpful defines
+// Helpful defines
-    #define GRAVE_MODS  (MOD_BIT(KC_LSFT)|MOD_BIT(KC_RSFT)|MOD_BIT(KC_LGUI)|MOD_BIT(KC_RGUI)|MOD_BIT(KC_LALT)|MOD_BIT(KC_RALT))
+#define GRAVE_MODS  (MOD_BIT(KC_LSFT)|MOD_BIT(KC_RSFT)|MOD_BIT(KC_LGUI)|MOD_BIT(KC_RGUI)|MOD_BIT(KC_LALT)|MOD_BIT(KC_RALT))
 
-    /* * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * 
+/* * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * 
-     *  You can use _______ in place for KC_TRNS (transparent)   *
+    *  You can use _______ in place for KC_TRNS (transparent)   *
-     *  Or you can use XXXXXXX for KC_NO (NOOP)                  *
+    *  Or you can use XXXXXXX for KC_NO (NOOP)                  *
-     * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * */
+    * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * */
 
-    // Each layer gets a name for readability.
+// Each layer gets a name for readability.
-    // The underscores don't mean anything - you can
+// The underscores don't mean anything - you can
-    // have a layer called STUFF or any other name.
+// have a layer called STUFF or any other name.
-    // Layer names don't all need to be of the same
+// Layer names don't all need to be of the same
-    // length, and you can also skip them entirely
+// length, and you can also skip them entirely
-    // and just use numbers.
+// and just use numbers.
-    enum layer_names {
+enum layer_names {
-        _BL,
+    _BL,
-        _FL,
+    _FL,
-        _CL,
+    _CL,
-    };
+};
+```
 
 These are some handy definitions we can use when building our keymap and our custom function. The `GRAVE_MODS` definition will be used later in our custom function, and the following `_BL`, `_FL`, and `_CL` defines make it easier to refer to each of our layers.
 
@@ -131,7 +138,9 @@ Note: You may also find some older keymap files may also have a define(s) for `_
 
 The main part of this file is the `keymaps[]` definition. This is where you list your layers and the contents of those layers. This part of the file begins with this definition:
 
-    const uint16_t PROGMEM keymaps[][MATRIX_ROWS][MATRIX_COLS] = {
+```c
+const uint16_t PROGMEM keymaps[][MATRIX_ROWS][MATRIX_COLS] = {
+```
 
 After this you'll find the layer definitions. Typically you'll have one or more "base layers" (such as QWERTY, Dvorak, or Colemak) and then you'll layer on top of that one or more "function" layers. Due to the way layers are processed you can't overlay a "lower" layer on top of a "higher" layer.
 

docs/newbs_building_firmware.md

@@ -8,7 +8,9 @@ You can configure your build environment to set the defaults and make working wi
 
 Most people new to QMK only have 1 keyboard. You can set this keyboard as your default with the `qmk config` command. For example, to set your default keyboard to `clueboard/66/rev4`:
 
-    qmk config user.keyboard=clueboard/66/rev4
+```sh
+qmk config user.keyboard=clueboard/66/rev4
+```
 
 ::: tip
 The keyboard option is the path relative to the keyboard directory, the above example would be found in `qmk_firmware/keyboards/clueboard/66/rev4`. If you're unsure you can view a full list of supported keyboards with `qmk list-keyboards`.
@@ -16,21 +18,29 @@ The keyboard option is the path relative to the keyboard directory, the above ex
 
 You can also set your default keymap name. Most people use their GitHub username like the keymap name from the previous steps:
 
-    qmk config user.keymap=<github_username>
+```sh
+qmk config user.keymap=<github_username>
+```
 
 ## Create a New Keymap
 
 To create your own keymap you'll want to create a copy of the `default` keymap. If you configured your build environment in the last step you can do that easily with the QMK CLI:
 
-    qmk new-keymap
+```sh
+qmk new-keymap
+```
 
 If you did not configure your environment, or you have multiple keyboards, you can specify a keyboard name:
 
-    qmk new-keymap -kb <keyboard_name>
+```sh
+qmk new-keymap -kb <keyboard_name>
+```
 
 Look at the output from that command, you should see something like this:
 
-    Ψ Created a new keymap called <github_username> in: /home/me/qmk_firmware/keyboards/clueboard/66/rev3/keymaps/<github_username>.
+```
+Ψ Created a new keymap called <github_username> in: /home/me/qmk_firmware/keyboards/clueboard/66/rev3/keymaps/<github_username>.
+```
 
 This is the location of your new `keymap.c` file.
 
@@ -38,7 +48,9 @@ This is the location of your new `keymap.c` file.
 
 Open your `keymap.c` file in your text editor. Inside this file you'll find the structure that controls how your keyboard behaves. At the top of `keymap.c` there may be some defines and enums that make the keymap easier to read. Farther down you'll find a line that looks like this:
 
-    const uint16_t PROGMEM keymaps[][MATRIX_ROWS][MATRIX_COLS] = {
+```c
+const uint16_t PROGMEM keymaps[][MATRIX_ROWS][MATRIX_COLS] = {
+```
 
 This line indicates where the list of Layers begins. Below that you'll find lines containing `LAYOUT`, and these lines indicate the start of a layer. Below that line is the list of keys that comprise a particular layer.
 
@@ -63,11 +75,15 @@ While you get a feel for how keymaps work, keep each change small. Bigger change
 
 When your changes to the keymap are complete you will need to build the firmware. To do so go back to your terminal window and run the compile command:
 
-    qmk compile
+```sh
+qmk compile
+```
 
 If you did not configure defaults for your environment, or you have multiple keyboards, you can specify a keyboard and/or keymap:
 
-    qmk compile -kb <keyboard> -km <keymap>
+```sh
+qmk compile -kb <keyboard> -km <keymap>
+```
 
 While this compiles you will have a lot of output going to the screen informing you of what files are being compiled. It should end with output that looks similar to this:
 

docs/newbs_flashing.md

@@ -98,17 +98,23 @@ Click the `Flash` button in QMK Toolbox. You will see output similar to the foll
 
 This has been made pretty simple compared to what it used to be. When you are ready to compile and flash your firmware, open up your terminal window and run the flash command:
 
-    qmk flash
+```sh
+qmk flash
+```
 
 If you did not configure your keyboard/keymap name in the CLI according to the [Configure your build environment](newbs_getting_started) section, or you have multiple keyboards, you can specify the keyboard and keymap:
 
-    qmk flash -kb <my_keyboard> -km <my_keymap>
+```sh
+qmk flash -kb <my_keyboard> -km <my_keymap>
+```
 
 This will check the keyboard's configuration, and then attempt to flash it based on the specified bootloader. This means that you don't need to know which bootloader that your keyboard uses. Just run the command, and let the command do the heavy lifting.
 
 However, this does rely on the bootloader being set by the keyboard. If this information is not configured, or you're using a board that doesn't have a supported target to flash it, you will see this error:
 
-    WARNING: This board's bootloader is not specified or is not supported by the ":flash" target at this time.
+```
+WARNING: This board's bootloader is not specified or is not supported by the ":flash" target at this time.
+```
 
 In this case, you'll have to fall back on specifying the bootloader. See the [Flashing Firmware](flashing) Guide for more details.
 

docs/newbs_getting_started.md

@@ -196,11 +196,15 @@ If you already know how to use GitHub, [we recommend that you follow these instr
 
 Now that your QMK build environment is set up, you can build a firmware for your keyboard. Start by trying to build the keyboard's default keymap. You should be able to do that with a command in this format:
 
-    qmk compile -kb <keyboard> -km default
+```sh
+qmk compile -kb <keyboard> -km default
+```
 
 For example, to build a firmware for a Clueboard 66% you would use:
 
-    qmk compile -kb clueboard/66/rev3 -km default
+```sh
+qmk compile -kb clueboard/66/rev3 -km default
+```
 
 ::: tip
 The keyboard option is the path relative to the keyboard directory, the above example would be found in `qmk_firmware/keyboards/clueboard/66/rev3`. If you're unsure you can view a full list of supported keyboards with `qmk list-keyboards`.