Updated documentation for Material for MkDocs Insiders

CHANGELOG

@@ -1,3 +1,7 @@
+mkdocs-material-6.1.7+insiders-1.12.0 (2020-12-06)
+
+  * Added support for adding a language selector
+
 mkdocs-material-6.1.7 (2020-12-06)
 
   * Fixed #2081: Fixed stats for private GitHub repositories

docs/changelog.md

@@ -6,6 +6,10 @@ template: overrides/main.html
 
 ## Material for MkDocs Insiders
 
+### 1.12.0 <small>_ December 6, 2020</small>
+
+- Added support for adding a language selector
+
 ### 1.11.2 <small>_ November 29, 2020</small>
 
 - Fixed #2068: Search highlight interprets code blocks as JavaScript

docs/insiders.md

@@ -114,6 +114,7 @@ for MkDocs Insiders. You can click on each feature to learn more about it:
 - [x] [Remove _Made with Material for MkDocs_ from footer][11]
 - [x] [Support for user-toggleable themes (light/dark mode switch)][12]
 - [x] [Support for deploying multiple versions][13]
+- [x] [Support for deploying multiple languages][22]
 - [x] [Search suggestions help to save keystrokes][14]
 - [x] [Highlighting of matched search terms in content area][15]
 - [x] Search goes to first result on ++enter++ (I'm feeling lucky)
@@ -135,19 +136,20 @@ for MkDocs Insiders. You can click on each feature to learn more about it:
   [19]: setup/setting-up-navigation.md#navigation-integration
   [20]: setup/setting-up-the-header.md#automatic-hiding
   [21]: reference/admonitions.md#inline-blocks
+  [22]: setup/changing-the-language.md#site-language-selector
 
 ## Roadmap
 
 The following list of funding goals – named after varieties of chili peppers 
-[I'm growing on my balcony][22] – shows which features are already available
+[I'm growing on my balcony][23] – shows which features are already available
 in Material for MkDocs Insiders.
 
-  [22]: https://www.instagram.com/squidfunk/
+  [23]: https://www.instagram.com/squidfunk/
 
 ### Madame Jeanette
 
 [:octicons-flame-24: Funding goal: __$500__][6] ·
-:octicons-unlock-24: Status: _released_
+:octicons-unlock-24: Status: _Generally available_
 
 - [x] Improved search result grouping (pages + headings)
 - [x] Improved search result relevance and scoring
@@ -156,7 +158,7 @@ in Material for MkDocs Insiders.
 ### Prairie Fire
 
 [:octicons-flame-24: Funding goal: __$1,000__][6] ·
-:octicons-lock-24: Status: _exclusive_
+:octicons-lock-24: Status: _Insiders only_
 
 - [x] [Navigation can be grouped into sections][16]
 - [x] [Navigation can be always expanded][17]
@@ -167,16 +169,16 @@ in Material for MkDocs Insiders.
 ### Bhut Jolokia
 
 [:octicons-flame-24: Funding goal: __$1,500__][6] ·
-:octicons-lock-24: Status: _exclusive_
+:octicons-lock-24: Status: _Insiders only_
 
 - [x] [Support for Admonitions as inline blocks][21]
 - [x] [Support for deploying multiple versions][13]
-- [ ] Support for deploying multiple languages
+- [x] [Support for deploying multiple languages][22]
 
 ### Black Pearl
 
 [:octicons-flame-24: Funding goal: __$2,000__][6] ·
-:octicons-lock-24: Status: _exclusive_
+:octicons-lock-24: Status: _Insiders only_
 
 - [x] [Support for user-toggleable themes (light/dark mode switch)][12]
 - [ ] Support for user-toggleable code-block styles (light/dark mode switch)
@@ -185,7 +187,7 @@ in Material for MkDocs Insiders.
 ### Biquinho Vermelho
 
 [:octicons-flame-24: Funding goal: __$2,500__][6] ·
-:octicons-lock-24: Status: _exclusive_
+:octicons-lock-24: Status: _Insiders only_
 
 - [x] [Search suggestions help to save keystrokes][14]
 - [x] [Highlighting of matched search terms in content area][15]
@@ -197,7 +199,7 @@ in Material for MkDocs Insiders.
 ### Caribbean Red
 
 [:octicons-flame-24: Funding goal: __$3,000__][6] ·
-:octicons-lock-24: Status: _exclusive_
+:octicons-lock-24: Status: _Insiders only_
 
 - [x] [Remove _Made with Material for MkDocs_ from footer][11]
 - [ ] Brand-new and exclusive vertical layout
@@ -215,10 +217,10 @@ improvements (e.g. search) do not require any changes to existing configuration.
 This means that your users will be able to build the docs locally with the
 regular version and when they push their changes to CI/CD, they will be built
 with Material for MkDocs Insiders. For this reason, it's recommended to
-[install Insiders][23] only in CI, as you don't want to expose your `GH_TOKEN`
+[install Insiders][24] only in CI, as you don't want to expose your `GH_TOKEN`
 to users.
 
-  [23]: publishing-your-site.md#github-pages
+  [24]: publishing-your-site.md#github-pages
 
 ### Terms
 
@@ -228,7 +230,7 @@ terms?_
 
 Yes. Whether you're an individual or a company, you may use _Material for MkDocs
 Insiders_ precisely under the same terms as Material for MkDocs, which are given
-by the [MIT license][24]. However, we kindly ask you to respect the following
+by the [MIT license][25]. However, we kindly ask you to respect the following
 guidelines:
 
 - Please __don't distribute the source code__ from Material for MkDocs Insiders.
@@ -239,7 +241,7 @@ guidelines:
 - If you cancel your subscription, you're removed as a collaborator and will
   miss out on future updates of Material for MkDocs Insiders. However, you may
   __use the latest version__ that's available to you __as long as you like__.
-  Just remember that __[GitHub deletes private forks][25]__.
+  Just remember that __[GitHub deletes private forks][26]__.
 
-  [24]: license.md
+  [25]: license.md
-  [25]: https://docs.github.com/en/github/setting-up-and-managing-your-github-user-account/removing-a-collaborator-from-a-personal-repository
+  [26]: https://docs.github.com/en/github/setting-up-and-managing-your-github-user-account/removing-a-collaborator-from-a-personal-repository

docs/setup/changing-the-language.md

@@ -84,23 +84,70 @@ as [documented here][2]._
   [1]: https://github.com/squidfunk/mkdocs-material/blob/master/src/partials/language/en.html
   [2]: setting-up-navigation.md#slugify
 
-### Site search language
+### Site language selector
 
 [:octicons-file-code-24: Source][3] ·
+:octicons-beaker-24: Experimental ·
+[:octicons-heart-fill-24:{: .tx-heart } Insiders only][3]{: .tx-insiders }
+
+If your documentation is available in multiple languages, a _language selector_
+can be added to the header next to the search bar. Languages can be defined via
+`mkdocs.yml`:
+
+``` yaml
+extra:
+  alternate:
+    - name: English
+      link: https://squidfunk.github.io/mkdocs-material-insiders/en/
+      lang: en
+    - name: Deutsch
+      link: https://squidfunk.github.io/mkdocs-material-insiders/de/
+      lang: de
+    - name: 日本語
+      link: https://squidfunk.github.io/mkdocs-material-insiders/jp/
+      lang: jp
+```
+
+This will render a language selector in the header next to the search bar:
+
+  [![Language selection][4]][4]
+
+  [3]: ../insiders.md
+  [4]: ../assets/screenshots/language-selection.png
+
+This assumes that your project is structured into multiple subfolders, each of
+which contain the entire documentation for a given language, e.g.:
+
+``` sh
+.
+├─ en/
+│  ├─ docs/
+│  └─ mkdocs.yml
+├─ de/
+│  ├─ docs/
+│  └─ mkdocs.yml
+└─ jp/
+   ├─ docs/
+   └─ mkdocs.yml
+```
+
+### Site search language
+
+[:octicons-file-code-24: Source][5] ·
 :octicons-milestone-24: Default: _automatically set_
 
 Some languages, like Arabic or Japanese, need dedicated stemmers for search to
-work properly. Material for MkDocs relies on [lunr-languages][4] to provide this
+work properly. Material for MkDocs relies on [lunr-languages][6] to provide this
-functionality. See the guide detailing how to [set up site search][5] for
+functionality. See the guide detailing how to [set up site search][7] for
 more information.
 
-  [3]: https://github.com/squidfunk/mkdocs-material/blob/master/src/assets/javascripts/integrations/search/worker/main/index.ts#L77-L108
+  [5]: https://github.com/squidfunk/mkdocs-material/blob/master/src/assets/javascripts/integrations/search/worker/main/index.ts#L77-L108
-  [4]: https://github.com/MihaiValentin/lunr-languages
+  [6]: https://github.com/MihaiValentin/lunr-languages
-  [5]: setting-up-site-search.md
+  [7]: setting-up-site-search.md
 
 ### Directionality
 
-[:octicons-file-code-24: Source][6] ·
+[:octicons-file-code-24: Source][8] ·
 :octicons-milestone-24: Default: _automatically set_
 
 While many languages are read `ltr` (left-to-right), Material for MkDocs also
@@ -132,7 +179,7 @@ directionality:
   })
 </script>
 
-  [6]: https://github.com/squidfunk/mkdocs-material/blob/master/src/base.html#L185
+  [8]: https://github.com/squidfunk/mkdocs-material/blob/master/src/base.html#L185
 
 ## Customization
 
@@ -142,7 +189,7 @@ directionality:
 :octicons-mortar-board-24: Difficulty: _easy_
 
 If you want to customize some (or all) of the translations for your language,
-you may follow the guide on [theme extension][7] and create a new partial in
+you may follow the guide on [theme extension][9] and create a new partial in
 `partials/language`, e.g. `en-custom.html`. Next, look up the translation you
 want to change in the [base translation][1] and add it to the partial.
 
@@ -161,4 +208,4 @@ theme:
   language: en-custom
 ```
 
-  [7]: ../customization.md#extending-the-theme
+  [9]: ../customization.md#extending-the-theme

docs/setup/setting-up-versioning.md

@@ -33,7 +33,7 @@ extra:
 This will render a version selector in the header next to the title of your
 project:
 
-[![Versioning][3]][3]
+[![Version selection][3]][3]
 
 [Try this feature][4]{: .md-button .md-button--primary }