diff --git a/.gitignore b/.gitignore index 140bf4aa7e..5b21f27b08 100644 --- a/.gitignore +++ b/.gitignore @@ -73,3 +73,7 @@ id_rsa_* # python things __pycache__ + +# doc things +dist +node_modules diff --git a/docs/.vuepress/config.js b/docs/.vuepress/config.js new file mode 100644 index 0000000000..e282ff8950 --- /dev/null +++ b/docs/.vuepress/config.js @@ -0,0 +1,43 @@ +module.exports = { + title: 'QMK Firmware Documentation', + description: 'Quantum Mechanical Keyboard Firmware Documentation.', + markdown: { + lineNumbers: true + }, + themeConfig: { + displayAllHeaders: true, + docsDir: 'docs', + editLinks: true, + editLinkText: 'Suggest an improvement to this page!', + lastUpdated: 'Last Updated', + logo: '/favicon.png', + repo: 'qmk/qmk_api', + repoLabel: 'Fork', + nav: [ + { text: 'Home', link: '/' }, + { text: 'Chat', link: 'https://discord.gg/V5Trhu2' }, + ], + sidebar: [ + 'newbs', + '/', + 'faq', + 'detailed_guides', + 'reference', + 'features', + 'makers_modders', + 'deeper_understanding', + 'other_topics', + 'qmk_internals' + ] + }, + locales: { + '/': { + lang: 'en-US' + }, + '/zh/': { + lang: 'zh-CN', + title: 'QMK鍵盤固件', + description: 'QMK鍵盤固件' + } + } +} diff --git a/docs/.vuepress/public/color-wheel.svg b/docs/.vuepress/public/color-wheel.svg new file mode 100644 index 0000000000..83e599477f --- /dev/null +++ b/docs/.vuepress/public/color-wheel.svg @@ -0,0 +1,441 @@ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +image/svg+xmlOpenclipart diff --git a/docs/.vuepress/public/favicon.ico b/docs/.vuepress/public/favicon.ico new file mode 100644 index 0000000000..2b4e04abaf Binary files /dev/null and b/docs/.vuepress/public/favicon.ico differ diff --git a/docs/README.md b/docs/README.md index 22ab243cd2..dbc09dacb4 100644 --- a/docs/README.md +++ b/docs/README.md @@ -1,5 +1,7 @@ # Quantum Mechanical Keyboard Firmware +[[toc]] + [![Current Version](https://img.shields.io/github/tag/qmk/qmk_firmware.svg)](https://github.com/qmk/qmk_firmware/tags) [![Build Status](https://travis-ci.org/qmk/qmk_firmware.svg?branch=master)](https://travis-ci.org/qmk/qmk_firmware) [![Discord](https://img.shields.io/discord/440868230475677696.svg)](https://discord.gg/Uq7gcHh) diff --git a/docs/arm_debugging.md b/docs/arm_debugging.md index 491dfe8ad7..8ac9de460e 100644 --- a/docs/arm_debugging.md +++ b/docs/arm_debugging.md @@ -1,5 +1,7 @@ # ARM Debugging usign Eclipse +[[toc]] + This page describes how to setup debugging for ARM MCUs using an SWD adapter and open-source/free tools. In this guide we will install GNU MCU Eclipse IDE for C/C++ Developers and OpenOCD together with all the necessary dependencies. This guide is catered towards advance users and assumes you can compile an ARM compatible keyboard on your machine using the MAKE flow. @@ -84,4 +86,4 @@ Reset your keyboard. Press the bug icon and if all goes well you should soon find yourself in the debug perspective. Here the program counter will pause at the beginning of the main function and way for you to press Play. Most of the features of all debuggers work on ARM MCUs but for exact details google is your friend! -Happy debugging! \ No newline at end of file +Happy debugging! diff --git a/docs/becoming_a_qmk_collaborator.md b/docs/becoming_a_qmk_collaborator.md index 16ae0d569e..67d140fc55 100644 --- a/docs/becoming_a_qmk_collaborator.md +++ b/docs/becoming_a_qmk_collaborator.md @@ -1,5 +1,7 @@ # Becoming a QMK Collaborator +[[toc]] + A QMK collaborator is a keyboard maker or designer that is interested in helping QMK grow and fully support their keyboard(s), and encouraging their users and customers to submit features, ideas, and keymaps. We're always looking to add more keyboards and collaborators, but we ask that they fulfill these requirements: * **Have a PCB available for sale.** Unfortunately there's just too much variation and complications with handwired keyboards. diff --git a/docs/cli.md b/docs/cli.md index 0365f2c9c8..c3b42be702 100644 --- a/docs/cli.md +++ b/docs/cli.md @@ -1,5 +1,7 @@ # QMK CLI +[[toc]] + This page describes how to setup and use the QMK CLI. # Overview diff --git a/docs/coding_conventions_c.md b/docs/coding_conventions_c.md index cbddedf8b0..e869e11884 100644 --- a/docs/coding_conventions_c.md +++ b/docs/coding_conventions_c.md @@ -1,5 +1,7 @@ # Coding Conventions (C) +[[toc]] + Most of our style is pretty easy to pick up on, but right now it's not entirely consistent. You should match the style of the code surrounding your change, but if that code is inconsistent or unclear use the following guidelines: * We indent using four (4) spaces (soft tabs) diff --git a/docs/coding_conventions_python.md b/docs/coding_conventions_python.md index c7743050e2..44e88c10fa 100644 --- a/docs/coding_conventions_python.md +++ b/docs/coding_conventions_python.md @@ -1,5 +1,7 @@ # Coding Conventions (Python) +[[toc]] + Most of our style follows PEP8 with some local modifications to make things less nit-picky. * We target Python 3.5 for compatability with all supported platforms. diff --git a/docs/compatible_microcontrollers.md b/docs/compatible_microcontrollers.md index 6e3f8372c9..aa21d45c4a 100644 --- a/docs/compatible_microcontrollers.md +++ b/docs/compatible_microcontrollers.md @@ -1,5 +1,7 @@ # Atmel AVR +[[toc]] + QMK should run on any Atmel AVR processor with enough Flash. It has been tested on the following: * ATmega32U4 ([PJRC Teensy 2.0](http://www.pjrc.com/teensy/)) diff --git a/docs/config_options.md b/docs/config_options.md index 3012dcdcff..46806f4701 100644 --- a/docs/config_options.md +++ b/docs/config_options.md @@ -1,5 +1,7 @@ # Configuring QMK +[[toc]] + QMK is nearly infinitely configurable. Wherever possible we err on the side of allowing users to customize their keyboard, even at the expense of code size. That level of flexibility makes for a daunting configuration experience, however. There are two main types of configuration files in QMK- `config.h` and `rules.mk`. These files exist at various levels in QMK and all files of the same type are combined to build the final configuration. The levels, from lowest priority to highest priority, are: diff --git a/docs/contributing.md b/docs/contributing.md index 761bc9959b..5929ad6ac1 100644 --- a/docs/contributing.md +++ b/docs/contributing.md @@ -1,5 +1,7 @@ # How to Contribute +[[toc]] + 👍🎉 First off, thanks for taking the time to read this and contribute! 🎉👍 Third-party contributions help us grow and improve QMK. We want to make the pull request and contribution process useful and easy for both contributors and maintainers. To this end we've put together some guidelines for contributors to help your pull request be accepted without major changes. diff --git a/docs/custom_quantum_functions.md b/docs/custom_quantum_functions.md index 7be82c650f..e706bd8aef 100644 --- a/docs/custom_quantum_functions.md +++ b/docs/custom_quantum_functions.md @@ -1,5 +1,7 @@ # How to Customize Your Keyboard's Behavior +[[toc]] + For a lot of people a custom keyboard is about more than sending button presses to your computer. You want to be able to do things that are more complex than simple button presses and macros. QMK has hooks that allow you to inject code, override functionality, and otherwise customize how your keyboard behaves in different situations. This page does not assume any special knowledge about QMK, but reading [Understanding QMK](understanding_qmk.md) will help you understand what is going on at a more fundamental level. diff --git a/docs/deeper_understanding.md b/docs/deeper_understanding.md new file mode 100644 index 0000000000..fdd9640214 --- /dev/null +++ b/docs/deeper_understanding.md @@ -0,0 +1 @@ +# For a Deeper Understanding diff --git a/docs/detailed_guides.md b/docs/detailed_guides.md new file mode 100644 index 0000000000..5c8188a2f7 --- /dev/null +++ b/docs/detailed_guides.md @@ -0,0 +1,3 @@ +# Detailed Guides + +* TBD diff --git a/docs/documentation_best_practices.md b/docs/documentation_best_practices.md index 77c226117c..310392b3a0 100644 --- a/docs/documentation_best_practices.md +++ b/docs/documentation_best_practices.md @@ -1,5 +1,7 @@ # Documentation Best Practices +[[toc]] + This page exists to document best practices when writing documentation for QMK. Following these guidelines will help to keep a consistent tone and style, which will in turn help other people more easily understand QMK. # Page Opening diff --git a/docs/documentation_templates.md b/docs/documentation_templates.md index ba3830b64c..bfdf9adbea 100644 --- a/docs/documentation_templates.md +++ b/docs/documentation_templates.md @@ -1,5 +1,7 @@ # Documentation Templates +[[toc]] + This page documents the templates you should use when submitting new Keymaps and Keyboards to QMK. ## Keymap `readme.md` Template diff --git a/docs/faq.md b/docs/faq.md index 506f57a72b..0113589ecb 100644 --- a/docs/faq.md +++ b/docs/faq.md @@ -1,5 +1,7 @@ # Frequently Asked Questions +[[toc]] + * [General](faq_general.md) * [Building or Compiling QMK](faq_build.md) * [Debugging and Troubleshooting QMK](faq_debug.md) diff --git a/docs/faq_build.md b/docs/faq_build.md index 23d6a67021..df19d3ed73 100644 --- a/docs/faq_build.md +++ b/docs/faq_build.md @@ -1,5 +1,7 @@ # Frequently Asked Build Questions +[[toc]] + This page covers questions about building QMK. If you haven't yet done so, you should read the [Build Environment Setup](getting_started_build_tools.md) and [Make Instructions](getting_started_make_guide.md) guides. ## Can't Program on Linux diff --git a/docs/faq_debug.md b/docs/faq_debug.md index f6cc729b61..81139270a3 100644 --- a/docs/faq_debug.md +++ b/docs/faq_debug.md @@ -1,5 +1,7 @@ # Debugging FAQ +[[toc]] + This page details various common questions people have about troubleshooting their keyboards. # Debug Console diff --git a/docs/faq_general.md b/docs/faq_general.md index e0d8c69f21..fbcaf392f3 100644 --- a/docs/faq_general.md +++ b/docs/faq_general.md @@ -1,5 +1,7 @@ # Frequently Asked Questions +[[toc]] + ## What is QMK? [QMK](https://github.com/qmk), short for Quantum Mechanical Keyboard, is a group of people building tools for custom keyboards. We started with the [QMK firmware](https://github.com/qmk/qmk_firmware), a heavily modified fork of [TMK](https://github.com/tmk/tmk_keyboard). diff --git a/docs/faq_keymap.md b/docs/faq_keymap.md index 0a627469e7..b81b50db73 100644 --- a/docs/faq_keymap.md +++ b/docs/faq_keymap.md @@ -1,5 +1,7 @@ # Keymap FAQ +[[toc]] + This page covers questions people often have about keymaps. If you haven't you should read [Keymap Overview](keymap.md) first. ## What Keycodes Can I Use? diff --git a/docs/feature_advanced_keycodes.md b/docs/feature_advanced_keycodes.md index f748ccd70c..f9113b320f 100644 --- a/docs/feature_advanced_keycodes.md +++ b/docs/feature_advanced_keycodes.md @@ -1,5 +1,7 @@ # Advanced Keycodes +[[toc]] + Your keymap can include keycodes that are more advanced than normal, for example keys that switch layers or send modifiers when held, but send regular keycodes when tapped. This page documents the functions that are available to you. ## Assigning Custom Names diff --git a/docs/feature_audio.md b/docs/feature_audio.md index 7511598bcf..7adc91b5cb 100644 --- a/docs/feature_audio.md +++ b/docs/feature_audio.md @@ -1,5 +1,7 @@ # Audio +[[toc]] + Your keyboard can make sounds! If you've got a Planck, Preonic, or basically any AVR keyboard that allows access to certain PWM-capable pins, you can hook up a simple speaker and make it beep. You can use those beeps to indicate layer transitions, modifiers, special keys, or just to play some funky 8bit tunes. Up to two simultaneous audio voices are supported, one driven by timer 1 and another driven by timer 3. The following pins can be defined as audio outputs in config.h: diff --git a/docs/feature_auto_shift.md b/docs/feature_auto_shift.md index 9b4b296249..d3f3f0392d 100644 --- a/docs/feature_auto_shift.md +++ b/docs/feature_auto_shift.md @@ -1,5 +1,7 @@ # Auto Shift: Why Do We Need a Shift Key? +[[toc]] + Tap a key and you get its character. Tap a key, but hold it *slightly* longer and you get its shifted state. Voilà! No shift key needed! diff --git a/docs/feature_backlight.md b/docs/feature_backlight.md index 64c663076b..56f5524f88 100644 --- a/docs/feature_backlight.md +++ b/docs/feature_backlight.md @@ -1,5 +1,7 @@ # Backlighting +[[toc]] + Many keyboards support backlit keys by way of individual LEDs placed through or underneath the keyswitches. QMK is able to control the brightness of these LEDs by switching them on and off rapidly in a certain ratio, a technique known as *Pulse Width Modulation*, or PWM. By altering the duty cycle of the PWM signal, it creates the illusion of dimming. The MCU can only supply so much current to its GPIO pins. Instead of powering the backlight directly from the MCU, the backlight pin is connected to a transistor or MOSFET that switches the power to the LEDs. diff --git a/docs/feature_bluetooth.md b/docs/feature_bluetooth.md index 3ffbfa0680..d381d8ec5a 100644 --- a/docs/feature_bluetooth.md +++ b/docs/feature_bluetooth.md @@ -1,5 +1,7 @@ # Bluetooth +[[toc]] + ## Bluetooth Known Supported Hardware Currently Bluetooth support is limited to AVR based chips. For Bluetooth 2.1 Qmk has support for RN-42 HID Firmware and Bluefruit EZ Key the later of which is not produced anymore. For more recent BLE protocols currently only the Adafruit Bluefruit SPI friend is directly supported. BLE is needed to connect to iOS devices. Note iOS does not support Mouse Input. diff --git a/docs/feature_bootmagic.md b/docs/feature_bootmagic.md index 225189ccb7..b1d73220b6 100644 --- a/docs/feature_bootmagic.md +++ b/docs/feature_bootmagic.md @@ -1,5 +1,7 @@ # Bootmagic +[[toc]] + There are three separate but related features that allow you to change the behavior of your keyboard without reflashing. While each of them have similar functionality, it is accessed in different ways depending on how your keyboard is configured. **Bootmagic** is a system for configuring your keyboard while it initializes. To trigger a Bootmagic command, hold down the Bootmagic key and one or more command keys. diff --git a/docs/feature_combo.md b/docs/feature_combo.md index 9db7be5119..7b3d5031e3 100644 --- a/docs/feature_combo.md +++ b/docs/feature_combo.md @@ -1,5 +1,7 @@ # Combos +[[toc]] + The Combo feature is a chording type solution for adding custom actions. It lets you hit multiple keys at once and produce a different effect. For instance, hitting `A` and `S` within the tapping term would hit `ESC` instead, or have it perform even more complex tasks. To enable this feature, yu need to add `COMBO_ENABLE = yes` to your `rules.mk`. diff --git a/docs/feature_command.md b/docs/feature_command.md index deabedc1c3..8b3f63a841 100644 --- a/docs/feature_command.md +++ b/docs/feature_command.md @@ -1,5 +1,7 @@ # Command +[[toc]] + Command, formerly known as Magic, is a way to change your keyboard's behavior without having to flash or unplug it to use [Bootmagic](feature_bootmagic.md). There is a lot of overlap between this functionality and the [Bootmagic Keycodes](feature_bootmagic.md#keycodes). Wherever possible we encourage you to use that feature instead of Command. On some keyboards Command is disabled by default. If this is the case, it must be explicitly enabled in your `rules.mk`: diff --git a/docs/feature_debounce_type.md b/docs/feature_debounce_type.md index 38eca3f37c..0a0d21d953 100644 --- a/docs/feature_debounce_type.md +++ b/docs/feature_debounce_type.md @@ -1,5 +1,7 @@ # Debounce algorithm +[[toc]] + QMK supports multiple debounce algorithms through its debounce API. The logic for which debounce method called is below. It checks various defines that you have set in rules.mk diff --git a/docs/feature_dynamic_macros.md b/docs/feature_dynamic_macros.md index 0d11a28641..7d64c39244 100644 --- a/docs/feature_dynamic_macros.md +++ b/docs/feature_dynamic_macros.md @@ -1,5 +1,7 @@ # Dynamic Macros: Record and Replay Macros in Runtime +[[toc]] + QMK supports temporary macros created on the fly. We call these Dynamic Macros. They are defined by the user from the keyboard and are lost when the keyboard is unplugged or otherwise rebooted. You can store one or two macros and they may have a combined total of 128 keypresses. You can increase this size at the cost of RAM. diff --git a/docs/feature_encoders.md b/docs/feature_encoders.md index bb2d538e7e..59e738ba20 100644 --- a/docs/feature_encoders.md +++ b/docs/feature_encoders.md @@ -1,5 +1,7 @@ # Encoders +[[toc]] + Basic encoders are supported by adding this to your `rules.mk`: ENCODER_ENABLE = yes diff --git a/docs/feature_grave_esc.md b/docs/feature_grave_esc.md index f57c6042ca..00076c69f2 100644 --- a/docs/feature_grave_esc.md +++ b/docs/feature_grave_esc.md @@ -1,5 +1,7 @@ # Grave Escape +[[toc]] + If you're using a 60% keyboard, or any other layout with no F-row, you will have noticed that there is no dedicated Escape key. Grave Escape is a feature that allows you to share the grave key (` and `~`) with Escape. ## Usage diff --git a/docs/feature_haptic_feedback.md b/docs/feature_haptic_feedback.md index 85fd439640..f467ce731a 100644 --- a/docs/feature_haptic_feedback.md +++ b/docs/feature_haptic_feedback.md @@ -1,5 +1,7 @@ # Haptic Feedback +[[toc]] + ## Haptic feedback rules.mk options The following options are currently available for haptic feedback in `rule.mk`: diff --git a/docs/feature_hd44780.md b/docs/feature_hd44780.md index e9d9e8b7b8..6bff40f414 100644 --- a/docs/feature_hd44780.md +++ b/docs/feature_hd44780.md @@ -1,5 +1,7 @@ # HD44780 LCD Displays +[[toc]] + This is an integration of Peter Fleury's LCD library. This page will explain the basics. [For in depth documentation visit his page.](http://homepage.hispeed.ch/peterfleury/doxygen/avr-gcc-libraries/group__pfleury__lcd.html) You can enable support for HD44780 Displays by setting the `HD44780_ENABLE` flag in your keyboards `rules.mk` to yes. This will use about 400 KB of extra space. diff --git a/docs/feature_key_lock.md b/docs/feature_key_lock.md index 718d9c5bd1..6b05559236 100644 --- a/docs/feature_key_lock.md +++ b/docs/feature_key_lock.md @@ -1,5 +1,7 @@ # Key Lock +[[toc]] + Sometimes you may find yourself needing to hold down a specific key for a long period of time. Key Lock holds down the next key you press for you. Press it again, and it will be released. Let's say you need to type in ALL CAPS for a few sentences. Hit `KC_LOCK`, and then Shift. Now, Shift will be considered held until you tap it again. You can think of Key Lock as Caps Lock, but supercharged. diff --git a/docs/feature_layouts.md b/docs/feature_layouts.md index b34fd442d5..f14a6c1cf4 100644 --- a/docs/feature_layouts.md +++ b/docs/feature_layouts.md @@ -1,5 +1,7 @@ # Layouts: Using a Keymap with Multiple Keyboards +[[toc]] + The `layouts/` folder contains different physical key layouts that can apply to different keyboards. ``` diff --git a/docs/feature_leader_key.md b/docs/feature_leader_key.md index 82cf789017..198fd51dd3 100644 --- a/docs/feature_leader_key.md +++ b/docs/feature_leader_key.md @@ -1,5 +1,7 @@ # The Leader Key: A New Kind of Modifier +[[toc]] + If you've ever used Vim, you know what a Leader key is. If not, you're about to discover a wonderful concept. :) Instead of hitting Alt+Shift+W for example (holding down three keys at the same time), what if you could hit a _sequence_ of keys instead? So you'd hit our special modifier (the Leader key), followed by W and then C (just a rapid succession of keys), and something would happen. That's what `KC_LEAD` does. Here's an example: diff --git a/docs/feature_led_matrix.md b/docs/feature_led_matrix.md index 372407b90c..8997ee40af 100644 --- a/docs/feature_led_matrix.md +++ b/docs/feature_led_matrix.md @@ -1,5 +1,7 @@ # LED Matrix Lighting +[[toc]] + This feature allows you to use LED matrices driven by external drivers. It hooks into the backlight system so you can use the same keycodes as backlighting to control it. If you want to use RGB LED's you should use the [RGB Matrix Subsystem](feature_rgb_matrix.md) instead. diff --git a/docs/feature_macros.md b/docs/feature_macros.md index d81c3c6559..e91dd160fd 100644 --- a/docs/feature_macros.md +++ b/docs/feature_macros.md @@ -1,5 +1,7 @@ # Macros +[[toc]] + Macros allow you to send multiple keystrokes when pressing just one key. QMK has a number of ways to define and use macros. These can do anything you want: type common phrases for you, copypasta, repetitive game movements, or even help you code. !> **Security Note**: While it is possible to use macros to send passwords, credit card numbers, and other sensitive information it is a supremely bad idea to do so. Anyone who gets a hold of your keyboard will be able to access that information by opening a text editor. diff --git a/docs/feature_mouse_keys.md b/docs/feature_mouse_keys.md index 363662f633..8f7666158d 100644 --- a/docs/feature_mouse_keys.md +++ b/docs/feature_mouse_keys.md @@ -1,5 +1,7 @@ # Mouse keys +[[toc]] + Mouse keys is a feature that allows you to emulate a mouse using your keyboard. You can move the pointer at different speeds, press 5 buttons and scroll in 8 directions. ## Adding mouse keys to your keyboard diff --git a/docs/feature_oled_driver.md b/docs/feature_oled_driver.md index 503e438288..3f60b41cb0 100644 --- a/docs/feature_oled_driver.md +++ b/docs/feature_oled_driver.md @@ -1,5 +1,7 @@ # OLED Driver +[[toc]] + ## OLED Supported Hardware OLED modules using SSD1306 or SH1106 driver ICs, communicating over I2C. diff --git a/docs/feature_pointing_device.md b/docs/feature_pointing_device.md index 8ad428939a..98f077af98 100644 --- a/docs/feature_pointing_device.md +++ b/docs/feature_pointing_device.md @@ -1,5 +1,7 @@ ## Pointing Device +[[toc]] + Pointing Device is a generic name for a feature intended to be generic: moving the system pointer around. There are certainly other options for it - like mousekeys - but this aims to be easily modifiable and lightweight. You can implement custom keys to control functionality, or you can gather information from other peripherals and insert it directly here - let QMK handle the processing for you. To enable Pointing Device, uncomment the following line in your rules.mk: diff --git a/docs/feature_ps2_mouse.md b/docs/feature_ps2_mouse.md index 01e2cc63db..86d21d7c0b 100644 --- a/docs/feature_ps2_mouse.md +++ b/docs/feature_ps2_mouse.md @@ -1,5 +1,7 @@ ## PS/2 Mouse Support +[[toc]] + Its possible to hook up a PS/2 mouse (for example touchpads or trackpoints) to your keyboard as a composite device. To hook up a Trackpoint, you need to obtain a Trackpoint module (i.e. harvest from a Thinkpad keyboard), identify the function of each pin of the module, and make the necessary circuitry between controller and Trackpoint module. For more information, please refer to [Trackpoint Hardware](https://deskthority.net/wiki/TrackPoint_Hardware) page on Deskthority Wiki. diff --git a/docs/feature_rgb_matrix.md b/docs/feature_rgb_matrix.md index 916fcdce03..0bd224e036 100644 --- a/docs/feature_rgb_matrix.md +++ b/docs/feature_rgb_matrix.md @@ -1,5 +1,7 @@ # RGB Matrix Lighting +[[toc]] + This feature allows you to use RGB LED matrices driven by external drivers. It hooks into the RGBLIGHT system so you can use the same keycodes as RGBLIGHT to control it. If you want to use single color LED's you should use the [LED Matrix Subsystem](feature_led_matrix.md) instead. diff --git a/docs/feature_rgblight.md b/docs/feature_rgblight.md index be4ddfa729..ade16ebbfd 100644 --- a/docs/feature_rgblight.md +++ b/docs/feature_rgblight.md @@ -1,5 +1,7 @@ # RGB Lighting +[[toc]] + QMK has the ability to control RGB LEDs attached to your keyboard. This is commonly called *underglow*, due to the LEDs often being mounted on the bottom of the keyboard, producing a nice diffused effect when combined with a translucent case. ![Planck with RGB Underglow](https://raw.githubusercontent.com/qmk/qmk_firmware/3774a7fcdab5544fc787f4c200be05fcd417e31f/keyboards/planck/keymaps/yang/planck-with-rgb-underglow.jpg) diff --git a/docs/feature_space_cadet.md b/docs/feature_space_cadet.md index 41a44627e3..357990e2f0 100644 --- a/docs/feature_space_cadet.md +++ b/docs/feature_space_cadet.md @@ -1,5 +1,7 @@ # Space Cadet: The Future, Built In +[[toc]] + Steve Losh described the [Space Cadet Shift](http://stevelosh.com/blog/2012/10/a-modern-space-cadet/) quite well. Essentially, when you tap Left Shift on its own, you get an opening parenthesis; tap Right Shift on its own and you get the closing one. When held, the Shift keys function as normal. Yes, it's as cool as it sounds, and now even cooler supporting Control and Alt as well! ## Usage diff --git a/docs/feature_split_keyboard.md b/docs/feature_split_keyboard.md index 95aceab223..c2e35e9899 100644 --- a/docs/feature_split_keyboard.md +++ b/docs/feature_split_keyboard.md @@ -1,5 +1,7 @@ # Split Keyboard +[[toc]] + Many keyboards in the QMK Firmware repo are "split" keyboards. They use two controllers—one plugging into USB, and the second connected by a serial or an I2C connection over a TRRS or similar cable. Split keyboards can have a lot of benefits, but there is some additional work needed to get them enabled. diff --git a/docs/feature_stenography.md b/docs/feature_stenography.md index 0b2c82422b..34b094a78e 100644 --- a/docs/feature_stenography.md +++ b/docs/feature_stenography.md @@ -1,5 +1,7 @@ # Stenography in QMK +[[toc]] + [Stenography](https://en.wikipedia.org/wiki/Stenotype) is a method of writing most often used by court reports, closed-captioning, and real-time transcription for the deaf. In stenography words are chorded syllable by syllable with a mixture of spelling, phonetic, and shortcut (briefs) strokes. Professional stenographers can reach 200-300 WPM without any of the strain usually found in standard typing and with far fewer errors (>99.9% accuracy). The [Open Steno Project](http://www.openstenoproject.org/) has built an open-source program called Plover that provides real-time translation of steno strokes into words and commands. It has an established dictionary and supports diff --git a/docs/feature_swap_hands.md b/docs/feature_swap_hands.md index 09e01d50d3..294f68cb8e 100644 --- a/docs/feature_swap_hands.md +++ b/docs/feature_swap_hands.md @@ -1,5 +1,7 @@ # Swap-Hands Action +[[toc]] + The swap-hands action allows support for one-handed typing without requiring a separate layer. Set `SWAP_HANDS_ENABLE` in the Makefile and define a `hand_swap_config` entry in your keymap. Now whenever the `ACTION_SWAP_HANDS` command key is pressed the keyboard is mirrored. For instance, to type "Hello, World" on QWERTY you would type `^Ge^s^s^w^c W^wr^sd` ## Configuration diff --git a/docs/feature_tap_dance.md b/docs/feature_tap_dance.md index b5e5218b09..d80e5e7152 100644 --- a/docs/feature_tap_dance.md +++ b/docs/feature_tap_dance.md @@ -1,5 +1,7 @@ # Tap Dance: A Single Key Can Do 3, 5, or 100 Different Things +[[toc]] + Hit the semicolon key once, send a semicolon. Hit it twice, rapidly -- send a colon. Hit it three times, and your keyboard's LEDs do a wild dance. That's just one example of what Tap Dance can do. It's one of the nicest community-contributed features in the firmware, conceived and created by [algernon](https://github.com/algernon) in [#451](https://github.com/qmk/qmk_firmware/pull/451). Here's how algernon describes the feature: diff --git a/docs/feature_terminal.md b/docs/feature_terminal.md index 1863599f84..0b45bd83c7 100644 --- a/docs/feature_terminal.md +++ b/docs/feature_terminal.md @@ -1,5 +1,7 @@ # Terminal +[[toc]] + > This feature is currently *huge* at 4400 bytes, and should probably only be put on boards with a lot of memory, or for fun. The terminal feature is a command-line-like interface designed to communicate through a text editor with keystrokes. It's beneficial to turn off auto-indent features in your editor. diff --git a/docs/feature_thermal_printer.md b/docs/feature_thermal_printer.md index 3f496646d4..e26a50e902 100644 --- a/docs/feature_thermal_printer.md +++ b/docs/feature_thermal_printer.md @@ -1,5 +1,7 @@ # Thermal Printer +[[toc]] + ## Thermal Printer Keycodes diff --git a/docs/feature_unicode.md b/docs/feature_unicode.md index bd1f4fa5ae..594a811fa9 100644 --- a/docs/feature_unicode.md +++ b/docs/feature_unicode.md @@ -1,5 +1,7 @@ # Unicode Support +[[toc]] + Unicode characters can be input straight from your keyboard! There are some limitations, however. QMK has three different methods for enabling Unicode input and defining keycodes: diff --git a/docs/feature_userspace.md b/docs/feature_userspace.md index 2f119c8bde..7009c9f980 100644 --- a/docs/feature_userspace.md +++ b/docs/feature_userspace.md @@ -1,5 +1,7 @@ # Userspace: Sharing Code Between Keymaps +[[toc]] + If you use more than one keyboard with a similar keymap, you might see the benefit in being able to share code between them. Create your own folder in `users/` named the same as your keymap (ideally your github username, ``) with the following structure: * `/users//` (added to the path automatically) diff --git a/docs/feature_velocikey.md b/docs/feature_velocikey.md index 5d98410735..abda0ecec4 100644 --- a/docs/feature_velocikey.md +++ b/docs/feature_velocikey.md @@ -1,5 +1,7 @@ # Velocikey +[[toc]] + Velocikey is a feature that lets you control the speed of lighting effects (like the Rainbow Swirl effect) with the speed of your typing. The faster you type, the faster the lights will go! ## Usage diff --git a/docs/features.md b/docs/features.md index f230c7c233..64d765e13e 100644 --- a/docs/features.md +++ b/docs/features.md @@ -1,5 +1,7 @@ # QMK Features +[[toc]] + QMK has a staggering number of features for building your keyboard. It can take some time to understand all of them and determine which one will achieve your goal. diff --git a/docs/flashing.md b/docs/flashing.md index 833b9dd629..d21cc43a73 100644 --- a/docs/flashing.md +++ b/docs/flashing.md @@ -1,5 +1,7 @@ # Flashing Instructions and Bootloader Information +[[toc]] + There are quite a few different types of bootloaders that keyboards use, and just about all of the use a different flashing method. Luckily, projects like the [QMK Toolbox](https://github.com/qmk/qmk_toolbox/releases) aim to be compatible with all the different types without having to think about it much, but this article will describe the different types of bootloaders, and available methods for flashing them. If you have a bootloader selected with the `BOOTLOADER` variable in your `rules.mk`, QMK will automatically calculate if your .hex file is the right size to be flashed to the device, and output the total size in bytes (along with the max). To run this process manually, compile with the target `check-size`, eg `make planck/rev4:default:check-size`. diff --git a/docs/getting_started_build_tools.md b/docs/getting_started_build_tools.md index 268cc94c38..12813ee353 100644 --- a/docs/getting_started_build_tools.md +++ b/docs/getting_started_build_tools.md @@ -1,5 +1,7 @@ # Installing Build Tools +[[toc]] + This page describes setting up the build environment for QMK. These instructions cover AVR processors (such as the atmega32u4). diff --git a/docs/getting_started_getting_help.md b/docs/getting_started_getting_help.md index 9788ad38e8..592a449ab8 100644 --- a/docs/getting_started_getting_help.md +++ b/docs/getting_started_getting_help.md @@ -1,5 +1,7 @@ # Getting Help +[[toc]] + There are a lot of resources for getting help with QMK. ## Realtime Chat diff --git a/docs/getting_started_github.md b/docs/getting_started_github.md index aeb8738b77..b943ce95d7 100644 --- a/docs/getting_started_github.md +++ b/docs/getting_started_github.md @@ -1,5 +1,7 @@ # How to Use Github with QMK +[[toc]] + Github can be a little tricky to those that aren't familiar with it - this guide will walk through each step of forking, cloning, and submitting a pull request with QMK. ?> This guide assumes you're somewhat comfortable with running things at the command line, and have git installed on your system. diff --git a/docs/getting_started_introduction.md b/docs/getting_started_introduction.md index e183d77eeb..9a48c21b2f 100644 --- a/docs/getting_started_introduction.md +++ b/docs/getting_started_introduction.md @@ -1,5 +1,7 @@ # Introduction +[[toc]] + This page attempts to explain the basic information you need to know to work with the QMK project. It assumes that you are familiar with navigating a Unix shell, but does not assume you are familiar with C or with compiling using make. ## Basic QMK Structure diff --git a/docs/getting_started_make_guide.md b/docs/getting_started_make_guide.md index 75eafd42cc..3e81c3aa2b 100644 --- a/docs/getting_started_make_guide.md +++ b/docs/getting_started_make_guide.md @@ -1,5 +1,7 @@ # More Detailed `make` Instructions +[[toc]] + The full syntax of the `make` command is `::`, where: * `` is the path of the keyboard, for example `planck` diff --git a/docs/getting_started_vagrant.md b/docs/getting_started_vagrant.md index b62524271c..ad16958544 100644 --- a/docs/getting_started_vagrant.md +++ b/docs/getting_started_vagrant.md @@ -1,5 +1,7 @@ # Vagrant Quick Start +[[toc]] + This project includes a `Vagrantfile` that will allow you to build a new firmware for your keyboard very easily without major changes to your primary operating system. This also ensures that when you clone the project and perform a build, you have the exact same environment as anyone else using the Vagrantfile to build. This makes it much easier for people to help you troubleshoot any issues you encounter. ## Requirements @@ -54,4 +56,4 @@ Execute the following to bypass the `vagrant` user booting directly to the offic ```console vagrant ssh -c 'sudo -i' -``` \ No newline at end of file +``` diff --git a/docs/hand_wire.md b/docs/hand_wire.md index 25db9341b8..71f72fe7f2 100644 --- a/docs/hand_wire.md +++ b/docs/hand_wire.md @@ -1,5 +1,7 @@ # Quantum Hand-Wiring Guide +[[toc]] + Parts list: * *x* keyswitches (MX, Matias, Gateron, etc) * *x* diodes diff --git a/docs/hardware.md b/docs/hardware.md index c3cc0e591e..fb5371eb89 100644 --- a/docs/hardware.md +++ b/docs/hardware.md @@ -1,5 +1,7 @@ # Hardware +[[toc]] + QMK runs on a variety of hardware. If your processor can be targeted by [LUFA](http://www.fourwalledcubicle.com/LUFA.php) or [ChibiOS](http://www.chibios.com) you can probably get QMK running on it. This section explores getting QMK running on, and communicating with, hardware of all kinds. * [Keyboard Guidelines](hardware_keyboard_guidelines.md) diff --git a/docs/hardware_avr.md b/docs/hardware_avr.md index 7c28ab6dbc..7b66a61730 100644 --- a/docs/hardware_avr.md +++ b/docs/hardware_avr.md @@ -1,5 +1,7 @@ # Keyboards with AVR Processors +[[toc]] + This page describes the support for for AVR processors in QMK. AVR processors include the atmega32u4, atmega32u2, at90usb1286, and other processors from Atmel Corporation. AVR processors are 8-bit MCU's that are designed to be easy to work with. The most common AVR processors in keyboards have on-board USB and plenty of GPIO for supporting large keyboard matrices. They are the most popular MCU for use in keyboards today. If you have not yet you should read the [Keyboard Guidelines](hardware_keyboard_guidelines.md) to get a sense of how keyboards fit into QMK. diff --git a/docs/hardware_drivers.md b/docs/hardware_drivers.md index 023e92982c..74557a698c 100644 --- a/docs/hardware_drivers.md +++ b/docs/hardware_drivers.md @@ -1,5 +1,7 @@ # QMK Hardware Drivers +[[toc]] + QMK is used on a lot of different hardware. While support for the most common MCU's and matrix configurations is built-in there are a number of drivers that can be added to a keyboard to support additional hardware. Examples include mice and other pointing devices, i/o expanders for split keyboards, bluetooth modules, and LCD, OLED, and TFT screens.