5 files changed, 57 insertions, 14 deletions

diff --git a/docs/_summary.md b/docs/_summary.md
index 808a8de4a..409df6d18 100644
--- a/docs/_summary.md
+++ b/docs/_summary.md
@@ -111,7 +111,7 @@
   * [Using Eclipse with QMK](other_eclipse.md)
   * [Using VSCode with QMK](other_vscode.md)
   * [Support](support.md)
-  * [How to add translations](translating.md)
+  * [Translating the QMK Docs](translating.md)
 
 * QMK Internals (In Progress)
   * [Defines](internals_defines.md)
diff --git a/docs/contributing.md b/docs/contributing.md
index 04dc0da20..7c365b418 100644
--- a/docs/contributing.md
+++ b/docs/contributing.md
@@ -101,6 +101,18 @@ enum my_keycodes {
 };
 ```
 
+### Previewing the Documentation
+
+Before opening a pull request, you can preview your changes if you have set up the development environment by running this command from the `qmk_firmware/` folder:
+
+    ./bin/qmk docs
+
+or if you only have Python 3 installed:
+
+    python3 -m http.server 8936
+
+and navigating to `http://localhost:8936/`.
+
 ## Keymaps
 
 Most first-time QMK contributors start with their personal keymaps. We try to keep keymap standards pretty casual (keymaps, after all, reflect the personality of their creators) but we do ask that you follow these guidelines to make it easier for others to discover and learn from your keymap.
diff --git a/docs/index.html b/docs/index.html
index d2ba99897..d20fbd64a 100644
--- a/docs/index.html
+++ b/docs/index.html
@@ -35,6 +35,15 @@
       loadNavbar: '_langs.md',
       mergeNavbar: true,
       auto2top: true,
+      fallbackLanguages: [
+        'de',
+        'es',
+        'fr-fr',
+        'he-il',
+        'ja',
+        'ru-ru',
+        'zh-cn'
+      ],
       formatUpdated: '{YYYY}/{MM}/{DD} {HH}:{mm}',
       search: {
         paths: 'auto',
diff --git a/docs/translating.md b/docs/translating.md
index 6eb268763..12fe7c85f 100644
--- a/docs/translating.md
+++ b/docs/translating.md
@@ -1,29 +1,49 @@
-# How to translate the QMK docs into different languages
+# Translating the QMK Docs
 
 All files in the root folder (`docs/`) should be in English - all other languages should be in subfolders with the ISO 639-1 language codes, followed by `-` and the country code where relevant. [A list of common ones can be found here](https://www.andiamo.co.uk/resources/iso-language-codes/). If this folder doesn't exist, you may create it. Each of the translated files should have the same name as the English version, so things can fall back successfully.
 
 A `_summary.md` file should exist in this folder with a list of links to each file, with a translated name, and link preceded by the language folder:
 
-    * [QMK简介](zh-cn/getting_started_introduction.md)
+```markdown
+ * [QMK简介](zh-cn/getting_started_introduction.md)
+```
+
+All links to other docs pages must also be prefixed with the language folder. If the link is to a specific part of the page (ie. a certain heading), you must use the English ID for the heading, like so:
+
+```markdown
+[建立你的环境](zh-cn/newbs-getting-started.md#set-up-your-environment)
+
+## 建立你的环境 :id=set-up-your-environment
+```
 
 Once you've finished translating a new language, you'll also need to modify the following files:
 
 * [`docs/_langs.md`](https://github.com/qmk/qmk_firmware/blob/master/docs/_langs.md)  
-  Each line should contain a country flag in the format `:us:` followed by the name represented in its own language:  
-  
-      - [:cn: 中文](/zh-cn/)
+  Each line should contain a country flag as a [GitHub emoji shortcode](https://github.com/ikatyang/emoji-cheat-sheet/blob/master/README.md#country-flag) followed by the name represented in its own language:
+
+  ```markdown
+   - [:cn: 中文](/zh-cn/)
+  ```
 
 * [`docs/index.html`](https://github.com/qmk/qmk_firmware/blob/master/docs/index.html)  
-  Both `placeholder` and `noData` objects should have a dictionary entry for the language folder in a string:  
-  
-      '/zh-cn/': '没有结果!',
+  Both `placeholder` and `noData` objects should have a dictionary entry for the language folder in a string:
+
+  ```js
+  '/zh-cn/': '没有结果!',
+  ```
 
-## Previewing the translations
+  And make sure to add the language folder in the `fallbackLanguages` list, so it will properly fall back to English instead of 404ing:
 
-Before opening a pull request, you can preview your additions if you have Python 3 installed by running this command in the `docs/` folder:
+  ```js
+  fallbackLanguages: [
+    // ...
+    'zh-cn',
+    // ...
+  ],
+  ```
 
-    python -m http.server 9000
+## Previewing the Translations
 
-and navigating to http://localhost:9000/ - you should be able to select your new language from the "Translations" menu at the top-right.
+See (Previewing the Documentation)[contributing.md#previewing-the-documentation] for how to set up a local instance of the docs - you should be able to select your new language from the "Translations" menu at the top-right.
 
 Once you're happy with your work, feel free to open a pull request!
diff --git a/readme.md b/readme.md
index 2641e2c2e..5a9166c04 100644
--- a/readme.md
+++ b/readme.md
@@ -13,7 +13,9 @@ This is a keyboard firmware based on the [tmk\_keyboard firmware](https://github
 
 * [See the official documentation on docs.qmk.fm](https://docs.qmk.fm)
 
-The docs are powered by [Docsify](https://docsify.js.org/) and hosted on [GitHub](/docs/). You can request changes by making a fork and [pull request](https://github.com/qmk/qmk_firmware/pulls), or by clicking the "Edit Document" link at the bottom of any page.
+The docs are powered by [Docsify](https://docsify.js.org/) and hosted on [GitHub](/docs/). They are also viewable offline; see [Previewing the Documentation](https://docs.qmk.fm/#/contributing?id=previewing-the-documentation) for more details.
+
+You can request changes by making a fork and opening a [pull request](https://github.com/qmk/qmk_firmware/pulls), or by clicking the "Edit Document" link at the bottom of any page.
 
 ## Supported Keyboards