varl/qmk_firmware
1
0
Fork 0
forked from forks/qmk_firmware
Code Pull requests Activity

Fix up info boxes.

Browse source
This commit is contained in:
skullY 2018-05-07 22:40:57 -07:00 committed by skullydazed
parent 9e5676650e
commit 303f425c6b
11 changed files with 122 additions and 94 deletions
Show stats Download patch file Download diff file Expand all files Collapse all files

61
docs/documentation_best_practices.md
View file

@ -22,60 +22,27 @@ Your page should generally have multiple "H1" headings. Only H1 and H2 headings
You can have styled hint blocks drawn around text to draw attention to it.
```
{% hint style='info' %}
This uses `hint style='info'`
{% endhint %}
```
### Examples:
{% hint style='info' %}
This uses `hint style='info'`
{% endhint %}
{% hint style='tip' %}
This uses `hint style='tip'`
{% endhint %}
{% hint style='danger' %}
This uses `hint style='danger'`
{% endhint %}
{% hint style='working' %}
This uses `hint style='working'`
{% endhint %}
# Styled Terminal Blocks
You can present styled terminal blocks by including special tokens inside your text block.
### Important
```
\`\`\`
**[terminal]
**[prompt foo@joe]**[path ~]**[delimiter $ ]**[command ./myscript]
Normal output line. Nothing special here...
But...
You can add some colors. What about a warning message?
**[warning [WARNING] The color depends on the theme. Could look normal too]
What about an error message?
**[error [ERROR] This is not the error you are looking for]
\`\`\`
!> This is important
```
### Example
Renders as:
!> This is important
### General Tips
```
**[terminal]
**[prompt foo@joe]**[path ~]**[delimiter $ ]**[command ./myscript]
Normal output line. Nothing special here...
But...
You can add some colors. What about a warning message?
**[warning [WARNING] The color depends on the theme. Could look normal too]
What about an error message?
**[error [ERROR] This is not the error you are looking for]
?> This is a helpful tip.
```
Renders as:
?> This is a helpful tip.
# Documenting Features
If you create a new feature for QMK, create a documentation page for it. It doesn't have to be very long, a few sentences describing your feature and a table listing any relevant keycodes is enough. Here is a basic template:
@ -94,4 +61,4 @@ This page describes my cool feature. You can use my cool feature to make coffee
|KC_SUGAR||Order Sugar|
```
Place your documentation into `docs/feature_<my_cool_feature>.md`, and add that file to the appropriate place in `docs/_summary.md`. If you have added any keycodes be sure to add them to `docs/keycodes.md` with a link back to your feature page.
Place your documentation into `docs/feature_<my_cool_feature>.md`, and add that file to the appropriate place in `docs/_sidebar.md`. If you have added any keycodes be sure to add them to `docs/keycodes.md` with a link back to your feature page.

6
docs/feature_advanced_keycodes.md
View file

@ -131,11 +131,9 @@ We've added shortcuts to make common modifier/tap (mod-tap) mappings more compac
* `LCAG_T(kc)` - is CtrlAltGui when held and *kc* when tapped
* `MEH_T(kc)` - is like Hyper, but not as cool -- does not include the Cmd/Win key, so just sends Alt+Ctrl+Shift.
{% hint style='info' %}
Due to the way that keycodes are structured, any modifiers specified as part of `kc`, such as `LCTL()` or `KC_LPRN`, will only activate when held instead of tapped.
?> Due to the way that keycodes are structured, any modifiers specified as part of `kc`, such as `LCTL()` or `KC_LPRN`, will only activate when held instead of tapped.
Additionally, if there is at least one right modifier, any other modifiers will turn into their right equivalents, so it is not possible to "mix and match" the two.
{% endhint %}
?> Additionally, if there is at least one right modifier, any other modifiers will turn into their right equivalents, so it is not possible to "mix and match" the two.
# One Shot Keys

5
docs/feature_auto_shift.md
View file

@ -88,10 +88,7 @@ occasion. This is simply due to habit and holding some keys a little longer
than others. Once you find this value, work on tapping your problem keys a little
quicker than normal and you will be set.
{% hint style='info' %}
Auto Shift has three special keys that can help you get this value right very
quick. See "Auto Shift Setup" for more details!
{% endhint %}
?> Auto Shift has three special keys that can help you get this value right very quick. See "Auto Shift Setup" for more details!
### NO_AUTO_SHIFT_SPECIAL (simple define)

8
docs/feature_macros.md
View file

@ -2,9 +2,7 @@
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.
{% hint style='danger' %}
**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.
{% endhint %}
!> **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.
## The New Way: `SEND_STRING()` & `process_record_user`
@ -132,9 +130,7 @@ SEND_STRING(".."SS_TAP(X_END));
## The Old Way: `MACRO()` & `action_get_macro`
{% hint style='info' %}
This is inherited from TMK, and hasn't been updated - it's recommend that you use `SEND_STRING` and `process_record_user` instead.
{% endhint %}
?> This is inherited from TMK, and hasn't been updated - it's recommend that you use `SEND_STRING` and `process_record_user` instead.
By default QMK assumes you don't have any macros. To define your macros you create an `action_get_macro()` function. For example:

4
docs/getting_started_github.md
View file

@ -2,9 +2,7 @@
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.
{% hint style='info' %}
This guide assumes you're somewhat comfortable with running things at the command line, and have git installed on your system.
{% endhint %}
?> This guide assumes you're somewhat comfortable with running things at the command line, and have git installed on your system.
Start on the [QMK Github page](https://github.com/qmk/qmk_firmware), and you'll see a button in the upper right that says "Fork":

4
docs/hardware_avr.md
View file

@ -66,9 +66,7 @@ Do change the `MANUFACTURER`, `PRODUCT`, and `DESCRIPTION` lines to accurately r
#define DESCRIPTION A custom keyboard
```
{% hint style='info' %}
Note: On Windows and macOS the `MANUFACTURER`, `PRODUCT`, and `DESCRIPTION` fields will be displayed in the list of USB devices. On Linux these values will not be visible in `lsusb`, since Linux takes that information from the list published by the USB-IF.
{% endhint %}
?> Note: On Windows and macOS the `MANUFACTURER`, `PRODUCT`, and `DESCRIPTION` fields will be displayed in the list of USB devices. On Linux these values will not be visible in `lsusb`, since Linux takes that information from the list published by the USB-IF.
### Keyboard Matrix Configuration

5
docs/index.html
View file

@ -28,5 +28,10 @@
<script src="//unpkg.com/prismjs/components/prism-cpp.min.js"></script>
<script src="//unpkg.com/prismjs/components/prism-json.min.js"></script>
<script src="//unpkg.com/prismjs/components/prism-makefile.min.js"></script>
<script>
if (typeof navigator.serviceWorker !== 'undefined') {
navigator.serviceWorker.register('sw.js')
}
</script>
</body>
</html>

16
docs/newbs_building_firmware.md
View file

@ -8,17 +8,15 @@ If you have closed and reopened your terminal window since following the first p
Start by navigating to the `keymaps` folder for your keyboard.
{% hint style='info' %}
If you are on macOS or Windows there are commands you can use to easily open the keymaps folder.
?> If you are on macOS or Windows there are commands you can use to easily open the keymaps folder.
macOS:
?> macOS:
open keyboards/<keyboard_folder>/keymaps
Windows:
?> Windows:
start keyboards/<keyboard_folder>/keymaps
{% endhint %}
## Create a Copy Of The `default` Keymap
@ -32,9 +30,7 @@ Open up your `keymap.c`. Inside this file you'll find the structure that control
This line indicates the start of the list of Layers. Below that you'll find lines containing either `LAYOUT` or `KEYMAP`, and these lines indicate the start of a layer. Below that line is the list of keys that comprise a that particular layer.
{% hint style='danger' %}
When editing your keymap file be careful not to add or remove any commas. If you do you will prevent your firmware from compiling and it may not be easy to figure out where the extra, or missing, comma is.
{% endhint %}
!> When editing your keymap file be careful not to add or remove any commas. If you do you will prevent your firmware from compiling and it may not be easy to figure out where the extra, or missing, comma is.
## Customize The Layout To Your Liking
@ -44,9 +40,7 @@ How to complete this step is entirely up to you. Make the one change that's been
* [Features](features.md)
* [FAQ](faq.md)
{% hint style='info' %}
While you get a feel for how keymaps work, keep each change small. Bigger changes make it harder to debug any problems that arise.
{% endhint %}
?> While you get a feel for how keymaps work, keep each change small. Bigger changes make it harder to debug any problems that arise.
## Build Your Firmware

8
docs/newbs_flashing.md
View file

@ -12,17 +12,15 @@ However, the QMK Toolbox is only available for Windows and macOS currently. If
Begin by opening the QMK Toolbox application. You'll want to locate the firmware file in Finder or Explorer. Your keyboard firmware may be in one of two formats- `.hex` or `.bin`. QMK tries to copy the appropriate one for your keyboard into the root `qmk_firmware` directory.
{% hint style='info' %}
If you are on Windows or macOS there are commands you can use to easily open the current firmware folder in Explorer or Finder.
?> If you are on Windows or macOS there are commands you can use to easily open the current firmware folder in Explorer or Finder.
Windows:
?> Windows:
start .
macOS:
?> macOS:
open .
{% endhint %}
The firmware file always follows this naming format:

16
docs/newbs_getting_started.md
View file

@ -14,9 +14,7 @@ Before you can build keymaps you need to install some software and setup your bu
You'll need a program that can edit and save **plain text** files. If you are on Windows you can make due with Notepad, and on Linux you can use Gedit, both of which are simple but functional text editors. On macOS you can not use TextEdit.app, it will not save plain text files. You will need to install another program such as Sublime Text.
{% hint style='info' %}
Not sure which text editor to use? Laurence Bradford wrote [a great introduction](https://learntocodewith.me/programming/basics/text-editors/) to the subject.
{% endhint %}
?> Not sure which text editor to use? Laurence Bradford wrote [a great introduction](https://learntocodewith.me/programming/basics/text-editors/) to the subject.
### QMK Toolbox
@ -29,12 +27,10 @@ QMK Toolbox is a Windows and macOS program that allows you to both program and d
We've tried to make QMK as easy to setup as possible. You only have to prepare your Linux or Unix environment and let QMK install the rest.
{% hint style="info" %}
If you haven't worked with the Linux/Unix command line before there are a few basic concepts and commands you should learn. These resources will teach you enough to work with QMK:
?> If you haven't worked with the Linux/Unix command line before there are a few basic concepts and commands you should learn. These resources will teach you enough to work with QMK:
* [Must Know Linux Commands](https://www.guru99.com/must-know-linux-commands.html)
* [Some Basic Unix Commands](https://www.tjhsst.edu/~dhyatt/superap/unixcmd.html)
{% endhint %}
?> * [Must Know Linux Commands](https://www.guru99.com/must-know-linux-commands.html)
?> * [Some Basic Unix Commands](https://www.tjhsst.edu/~dhyatt/superap/unixcmd.html)
### Windows
@ -63,9 +59,7 @@ Once you have setup your Linux/Unix environment you are ready to download QMK. W
git clone https://github.com/qmk/qmk_firmware.git
cd qmk_firmware
{% hint style='info' %}
If you already know [how to use GitHub](getting_started_github.md) we recommend you create and clone your own fork instead. If you don't know what that means you can safely ignore this message.
{% endhint %}
?> If you already know [how to use GitHub](getting_started_github.md) we recommend you create and clone your own fork instead. If you don't know what that means you can safely ignore this message.
## Setup QMK

83
docs/sw.js Normal file
View file

@ -0,0 +1,83 @@
/* ===========================================================
* docsify sw.js
* ===========================================================
* Copyright 2016 @huxpro
* Licensed under Apache 2.0
* Register service worker.
* ========================================================== */
const RUNTIME = 'docsify'
const HOSTNAME_WHITELIST = [
self.location.hostname,
'fonts.gstatic.com',
'fonts.googleapis.com',
'unpkg.com'
]
// The Util Function to hack URLs of intercepted requests
const getFixedUrl = (req) => {
var now = Date.now()
var url = new URL(req.url)
// 1. fixed http URL
// Just keep syncing with location.protocol
// fetch(httpURL) belongs to active mixed content.
// And fetch(httpRequest) is not supported yet.
url.protocol = self.location.protocol
// 2. add query for caching-busting.
// Github Pages served with Cache-Control: max-age=600
// max-age on mutable content is error-prone, with SW life of bugs can even extend.
// Until cache mode of Fetch API landed, we have to workaround cache-busting with query string.
// Cache-Control-Bug: https://bugs.chromium.org/p/chromium/issues/detail?id=453190
if (url.hostname === self.location.hostname) {
url.search += (url.search ? '&' : '?') + 'cache-bust=' + now
}
return url.href
}
/**
* @Lifecycle Activate
* New one activated when old isnt being used.
*
* waitUntil(): activating ====> activated
*/
self.addEventListener('activate', event => {
event.waitUntil(self.clients.claim())
})
/**
* @Functional Fetch
* All network requests are being intercepted here.
*
* void respondWith(Promise<Response> r)
*/
self.addEventListener('fetch', event => {
// Skip some of cross-origin requests, like those for Google Analytics.
if (HOSTNAME_WHITELIST.indexOf(new URL(event.request.url).hostname) > -1) {
// Stale-while-revalidate
// similar to HTTP's stale-while-revalidate: https://www.mnot.net/blog/2007/12/12/stale
// Upgrade from Jake's to Surma's: https://gist.github.com/surma/eb441223daaedf880801ad80006389f1
const cached = caches.match(event.request)
const fixedUrl = getFixedUrl(event.request)
const fetched = fetch(fixedUrl, { cache: 'no-store' })
const fetchedCopy = fetched.then(resp => resp.clone())
// Call respondWith() with whatever we get first.
// If the fetch fails (e.g disconnected), wait for the cache.
// If there’s nothing in cache, wait for the fetch.
// If neither yields a response, return offline pages.
event.respondWith(
Promise.race([fetched.catch(_ => cached), cached])
.then(resp => resp || fetched)
.catch(_ => { /* eat any errors */ })
)
// Update the cache with the version we fetched (only for ok status)
event.waitUntil(
Promise.all([fetchedCopy, caches.open(RUNTIME)])
.then(([response, cache]) => response.ok && cache.put(event.request, response))
.catch(_ => { /* eat any errors */ })
)
}
})