From 1855664ba973d96767bc13d039de6e8e0e717371 Mon Sep 17 00:00:00 2001
From: iBug <git@ibugone.com>
Date: Mon, 27 Jul 2020 16:37:37 +0800
Subject: [PATCH] Update documentation for #2621

---
 docs/_docs/01-quick-start-guide.md         | 16 ++++++++++------
 docs/_docs/06-overriding-theme-defaults.md |  3 ++-
 2 files changed, 12 insertions(+), 7 deletions(-)

diff --git a/docs/_docs/01-quick-start-guide.md b/docs/_docs/01-quick-start-guide.md
index 2a62f27a7d78..2987698b48a3 100644
--- a/docs/_docs/01-quick-start-guide.md
+++ b/docs/_docs/01-quick-start-guide.md
@@ -136,12 +136,17 @@ Depending on the path you took installing Minimal Mistakes you'll setup things a
 
 Starting with an empty folder and `Gemfile` you'll need to copy or re-create this [default `_config.yml`](https://github.com/mmistakes/minimal-mistakes/blob/master/_config.yml) file. For a full explanation of every setting be sure to read the [**Configuration**]({{ "/docs/configuration/" | relative_url }}) section.
 
-From `v4.5.0` onwards, Minimal Mistakes theme-gem comes bundled with the necessary data files and will automatically use them via the [`jekyll-data`](https://github.com/ashmaroli/jekyll-data) plugin. So you no longer need to maintain a copy of these data files at your project directory.
+From `v4.5.0` onwards, Minimal Mistakes theme-gem comes bundled with the necessary data files for localization.
+They will be picked up automatically if you have the [`jekyll-data`](https://github.com/ashmaroli/jekyll-data) plugin installed.
+If you're hosting on GitHub Pages, you can copy the [`_data/ui-text.yml`][ui-text.yml] file into your repository for the localization feature to work.
 
 You'll need to create and edit these data files to customize them:
 
-- [`_data/ui-text.yml`](https://github.com/mmistakes/minimal-mistakes/blob/master/_data/ui-text.yml) - UI text [documentation]({{ "/docs/ui-text/" | relative_url }})
-- [`_data/navigation.yml`](https://github.com/mmistakes/minimal-mistakes/blob/master/_data/navigation.yml) - navigation [documentation]({{ "/docs/navigation/" | relative_url }})
+- [`_data/ui-text.yml`][ui-text.yml] - UI text [documentation]({{ "/docs/ui-text/" | relative_url }})
+- [`_data/navigation.yml`][navigation.yml] - navigation [documentation]({{ "/docs/navigation/" | relative_url }})
+
+  [ui-text.yml]: https://github.com/mmistakes/minimal-mistakes/blob/master/_data/ui-text.yml
+  [navigation.yml]: https://github.com/mmistakes/minimal-mistakes/blob/master/_data/navigation.yml
 
 ### Starting from `jekyll new`
 
@@ -174,8 +179,7 @@ You won't need these anymore as they're bundled with the theme gem --- unless yo
 **Note:** When clearing out the `assets` folder be sure to leave any files you've added and need. This includes images, CSS, or JavaScript that aren't already [bundled in the theme](https://github.com/mmistakes/minimal-mistakes/tree/master/assets). 
 {: .notice--warning}
 
-From `v4.5.0` onwards, you don't have to maintain a copy of the default data files viz. `_data/ui-text.yml` and `_data/navigation.yml` either.
-The default files are read-in automatically via the [`jekyll-data`](https://github.com/ashmaroli/jekyll-data) plugin.
+From `v4.5.0` onwards, the default language files are read-in automatically via the [`jekyll-data`](https://github.com/ashmaroli/jekyll-data) plugin if it's installed. For sites hosted with GitHub Pages, you still need to copy the [`_data/ui-text.yml`][ui-text.yml] file because the `jekyll-data` plugin [is unsupported on GitHub Pages](https://docs.github.com/en/github/working-with-github-pages/about-github-pages-and-jekyll#plugins).
 
 If you customized any of these files leave them alone, and only remove the untouched ones. If done correctly your modified versions should [override](https://jekyllrb.com/docs/themes/#overriding-theme-defaults) the versions bundled with the theme and be used by Jekyll instead.
 
@@ -196,7 +200,7 @@ When finished your `Gemfile` should look something like this:
 ```ruby
 source "https://rubygems.org"
 
-gem "jekyll", "~> 3.5"
+gem "jekyll", "~> 3.7"
 gem "minimal-mistakes-jekyll"
 ```
 
diff --git a/docs/_docs/06-overriding-theme-defaults.md b/docs/_docs/06-overriding-theme-defaults.md
index 2999fbc8e077..65ce8e296157 100644
--- a/docs/_docs/06-overriding-theme-defaults.md
+++ b/docs/_docs/06-overriding-theme-defaults.md
@@ -21,7 +21,8 @@ Jekyll will use the files in your project first before falling back to the defau
 /_sass
 ```
 
-Additionally, from `v4.5.0` the theme-gem will also exhibit above behavior for `/_data` via a plugin.
+Additionally, from `v4.5.0` onwards the theme-gem will also exhibit above behavior for `/_data` via a plugin.
 Consequently, the data files for UI Text and Navigation are also bundled within the theme-gem.
+This doesn't apply if you're building your site on GitHub Pages, however.
 
 For more information on customizing the theme's [stylesheets]({{ "/docs/stylesheets/" | relative_url }}) and [JavaScript]({{ "/docs/javascript/" | relative_url }}), see the appropriate pages.