diff options
| -rw-r--r-- | docs/documentation_best_practices.md | 55 | ||||
| -rw-r--r-- | docs/feature_advanced_keycodes.md | 6 | ||||
| -rw-r--r-- | docs/feature_auto_shift.md | 5 | ||||
| -rw-r--r-- | docs/feature_macros.md | 8 | ||||
| -rw-r--r-- | docs/getting_started_github.md | 4 | ||||
| -rw-r--r-- | docs/hardware_avr.md | 4 | ||||
| -rw-r--r-- | docs/index.html | 5 | ||||
| -rw-r--r-- | docs/newbs_building_firmware.md | 16 | ||||
| -rw-r--r-- | docs/newbs_flashing.md | 8 | ||||
| -rw-r--r-- | docs/newbs_getting_started.md | 16 | ||||
| -rw-r--r-- | docs/sw.js | 83 |
11 files changed, 119 insertions, 91 deletions
diff --git a/docs/documentation_best_practices.md b/docs/documentation_best_practices.md index 80de8c039a..77c226117c 100644 --- a/docs/documentation_best_practices.md +++ b/docs/documentation_best_practices.md @@ -22,59 +22,26 @@ 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. +### Important + ``` -{% hint style='info' %} -This uses `hint style='info'` -{% endhint %} +!> This is important ``` -### 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 %} +Renders as: -{% hint style='working' %} -This uses `hint style='working'` -{% endhint %} +!> This is important -# Styled Terminal Blocks - -You can present styled terminal blocks by including special tokens inside your text block. +### 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. ``` -### Example +Renders as: + +?> This is a helpful tip. -``` -**[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] -``` # Documenting Features @@ -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. diff --git a/docs/feature_advanced_keycodes.md b/docs/feature_advanced_keycodes.md index 89d0ae8fcf..aeb7ce1bf4 100644 --- a/docs/feature_advanced_keycodes.md +++ b/docs/feature_advanced_keycodes.md @@ -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 diff --git a/docs/feature_auto_shift.md b/docs/feature_auto_shift.md index 484c506f13..9b4b296249 100644 --- a/docs/feature_auto_shift.md +++ b/docs/feature_auto_shift.md @@ -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) diff --git a/docs/feature_macros.md b/docs/feature_macros.md index 006fa04bca..6731530812 100644 --- a/docs/feature_macros.md +++ b/docs/feature_macros.md @@ -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: diff --git a/docs/getting_started_github.md b/docs/getting_started_github.md index f01ae6d011..7ce65e210e 100644 --- a/docs/getting_started_github.md +++ b/docs/getting_started_github.md @@ -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": diff --git a/docs/hardware_avr.md b/docs/hardware_avr.md index 7708170450..be69324062 100644 --- a/docs/hardware_avr.md +++ b/docs/hardware_avr.md @@ -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 diff --git a/docs/index.html b/docs/index.html index c890b95ae7..7955e47c29 100644 --- a/docs/index.html +++ b/docs/index.html @@ -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> diff --git a/docs/newbs_building_firmware.md b/docs/newbs_building_firmware.md index ea01a1a626..f227d623f0 100644 --- a/docs/newbs_building_firmware.md +++ b/docs/newbs_building_firmware.md @@ -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 diff --git a/docs/newbs_flashing.md b/docs/newbs_flashing.md index 4cd7c5c44a..0b0ede37c4 100644 --- a/docs/newbs_flashing.md +++ b/docs/newbs_flashing.md @@ -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: diff --git a/docs/newbs_getting_started.md b/docs/newbs_getting_started.md index 60b94b0123..8ada417eac 100644 --- a/docs/newbs_getting_started.md +++ b/docs/newbs_getting_started.md @@ -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 diff --git a/docs/sw.js b/docs/sw.js new file mode 100644 index 0000000000..1e4aaeb762 --- /dev/null +++ b/docs/sw.js @@ -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 */ }) + ) + } +}) |