Updated Insiders documentation

Author: squidfunk

CHANGELOG

@@ -1,3 +1,7 @@
+mkdocs-material-6.2.3+insiders-1.14.0 (2020-12-30)
+
+  * Added support for sharing searches
+
 mkdocs-material-6.2.3 (2020-12-27)
 
   * Added back hidden overflow on root container

docs/assets/screenshots/search-share.png

@@ -6,6 +6,10 @@ template: overrides/main.html
 
 ## Material for MkDocs Insiders
 
+### 1.14.0 <small>_ December 30, 2020</small>
+
+- Added support for sharing searches
+
 ### 1.13.2 <small>_ December 22, 2020</small>
 
 - Fixed version selector + sticky tabs navigation rendering issues

docs/changelog/insiders.md

@@ -103,11 +103,12 @@ The following features are currently exclusively available to sponsors:
 - [x] [Color palette toggle][15]
 - [x] [Versioning][14]
 - [x] [Site language selection][13]
-- [x] [Sticky navigation tabs][18]
+- [x] [Sticky navigation tabs][19]
+- [x] [Admonition inline blocks][12]
 - [x] [Search suggestions][16]
 - [x] [Search highlighting][17]
-- [x] [Admonition inline blocks][12]
-- [x] [Remove generator notice][19]
+- [x] [Search sharing][18]
+- [x] [Remove generator notice][20]
 
 </div>
 
@@ -137,7 +138,6 @@ the public for general availability.
 
 #### $ 2,000 – Black Pearl
 
-- [x] Deep linking of search results
 - [x] [Color palette toggle][15]
 - [ ] Code block palette toggle
 
@@ -147,31 +147,34 @@ the public for general availability.
 
 - [x] [Search suggestions][16]
 - [x] [Search highlighting][17]
-- [ ] List of last searches
+- [x] [Search sharing][18]
 
   [16]: setup/setting-up-site-search.md#search-suggestions
   [17]: setup/setting-up-site-search.md#search-highlighting
+  [18]: setup/setting-up-site-search.md#search-sharing
 
 #### $ 3,000 – Caribbean Red
 
-- [x] [Sticky navigation tabs][18]
-- [x] [Remove generator notice][19]
+- [x] [Sticky navigation tabs][19]
+- [x] [Remove generator notice][20]
 - [ ] Support for index pages
 
-  [18]: setup/setting-up-navigation.md#sticky-navigation-tabs
-  [19]: setup/setting-up-the-footer.md#remove-generator
+  [19]: setup/setting-up-navigation.md#sticky-navigation-tabs
+  [20]: setup/setting-up-the-footer.md#remove-generator
 
 #### Future
 
-- [ ] [Material for MkDocs Live Edit][20]
+- [ ] [Material for MkDocs Live Edit][21]
 - [ ] Improved search result summaries
+- [ ] List of last searches
+- [ ] Table of contents follows active anchor
 - [ ] Table of contents auto-collapse
 - [ ] Table of contents shows which sections have search results
 - [ ] Native lightbox for (inline) images
 - [ ] New layouts and styles (e.g. vertical)
 - [ ] ... and much more ...
 
-  [20]: https://twitter.com/squidfunk/status/1338252230265360391
+  [21]: https://twitter.com/squidfunk/status/1338252230265360391
 
 ### Goals completed
 
@@ -207,10 +210,10 @@ implemented behind feature flags; all configuration changes are
 backward-compatible. This means that your users will be able to build the
 documentation locally with Material for MkDocs and when they push their changes,
 it can be built with Insiders (e.g. as part of GitHub Actions). Thus, it's
-recommended to [install Insiders][21] only in CI, as you don't want to expose
+recommended to [install Insiders][22] only in CI, as you don't want to expose
 your `GH_TOKEN` to users.
 
-  [21]: publishing-your-site.md#github-pages
+  [22]: publishing-your-site.md#github-pages
 
 ### Terms
 
@@ -219,7 +222,7 @@ commercial project. Can we use Insiders under the same terms and conditions?_
 
 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][22]. However, we kindly ask you to respect the following
+by the [MIT license][23]. However, we kindly ask you to respect the following
 guidelines:
 
 - Please __don't distribute the source code__ of Insiders. You may freely use
@@ -230,7 +233,7 @@ guidelines:
 - If you cancel your subscription, you're removed as a collaborator and will
   miss out on future updates of 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][23].
+  [GitHub deletes private forks][24].
 
-  [22]: license.md
-  [23]: https://docs.github.com/en/github/setting-up-and-managing-your-github-user-account/removing-a-collaborator-from-a-personal-repository
+  [23]: license.md
+  [24]: https://docs.github.com/en/github/setting-up-and-managing-your-github-user-account/removing-a-collaborator-from-a-personal-repository

docs/insiders.md

@@ -203,22 +203,57 @@ A demo is worth a thousand words — check it out at
   [11]: ../assets/screenshots/search-highlighting.png
   [12]: https://squidfunk.github.io/mkdocs-material-insiders/reference/code-blocks/?h=code+blocks
 
+### Search sharing
+
+[:octicons-file-code-24: Source][8] ·
+:octicons-unlock-24: Feature flag ·
+:octicons-beaker-24: Experimental ·
+[:octicons-heart-fill-24:{: .tx-heart } Insiders only][8]{: .tx-insiders }
+
+When _search sharing_ is activated, a :material-share-variant: share button is
+rendered next to the reset button, which allows to deep link to the current
+search query and result. It can be enabled via `mkdocs.yml` with:
+
+``` yaml
+theme:
+  features:
+    - search.share
+```
+
+When a user clicks the share button, the URL is automatically copied to the
+clipboard.
+
+<figure markdown="1">
+
+[![Search sharing][13]][13]
+
+  <figcaption markdown="1">
+
+A demo is worth a thousand words — check it out at
+[squidfunk.github.io/mkdocs-material-insiders][14]
+
+  </figcaption>
+</figure>
+
+  [13]: ../assets/screenshots/search-share.png
+  [14]: https://squidfunk.github.io/mkdocs-material-insiders/setup/setting-up-site-search/?q=share+search
+
 ### Offline search
 
-[:octicons-file-code-24: Source][13] ·
-[:octicons-cpu-24: Plugin][14] · :octicons-beaker-24: Experimental
+[:octicons-file-code-24: Source][15] ·
+[:octicons-cpu-24: Plugin][16] · :octicons-beaker-24: Experimental
 
 If you distribute your documentation as `*.html` files, the built-in search
 will not work out-of-the-box due to the restrictions modern browsers impose for
-security reasons. This can be mitigated with the [localsearch][14] plugin in
-combination with @squidfunk's [iframe-worker][15] polyfill.
+security reasons. This can be mitigated with the [localsearch][16] plugin in
+combination with @squidfunk's [iframe-worker][17] polyfill.
 
-For setup instructions, refer to the [official documentation][16].
+For setup instructions, refer to the [official documentation][18].
 
-  [13]: https://github.com/squidfunk/mkdocs-material/blob/master/src/base.html
-  [14]: https://github.com/wilhelmer/mkdocs-localsearch/
-  [15]: https://github.com/squidfunk/iframe-worker
-  [16]: https://github.com/wilhelmer/mkdocs-localsearch#installation-material-v5
+  [15]: https://github.com/squidfunk/mkdocs-material/blob/master/src/base.html
+  [16]: https://github.com/wilhelmer/mkdocs-localsearch/
+  [17]: https://github.com/squidfunk/iframe-worker
+  [18]: https://github.com/wilhelmer/mkdocs-localsearch#installation-material-v5
 
 ## Customization
 
@@ -232,12 +267,12 @@ your needs.
 
 ### Query transformation
 
-[:octicons-file-code-24: Source][17] ·
+[:octicons-file-code-24: Source][19] ·
 :octicons-mortar-board-24: Difficulty: _easy_
 
 When a user enters a query into the search box, the query is pre-processed
 before it is submitted to the search index. Material for MkDocs will apply the
-following transformations, which can be customized by [extending the theme][18]:
+following transformations, which can be customized by [extending the theme][20]:
 
 ``` ts
 /**
@@ -277,7 +312,7 @@ export function defaultTransform(query: string): string {
 If you want to switch to the default behavior of the `mkdocs` or `readthedocs`
 template, both of which don't transform the query prior to submission, or
 customize the `transform` function, you can do this by [overriding the 
-`config` block][19]:
+`config` block][21]:
 
 ``` html
 {% block config %}
@@ -294,19 +329,19 @@ customize the `transform` function, you can do this by [overriding the
 The `transform` function will receive the query string as entered by the user
 and must return the processed query string to be submitted to the search index.
 
-  [17]: https://github.com/squidfunk/mkdocs-material/blob/master/src/assets/javascripts/integrations/search/transform/index.ts
-  [18]: ../customization.md#extending-the-theme
-  [19]: ../customization.md#overriding-blocks
+  [19]: https://github.com/squidfunk/mkdocs-material/blob/master/src/assets/javascripts/integrations/search/transform/index.ts
+  [20]: ../customization.md#extending-the-theme
+  [21]: ../customization.md#overriding-blocks
 
 ### Custom search
 
-[:octicons-file-code-24: Source][20] ·
+[:octicons-file-code-24: Source][22] ·
 :octicons-mortar-board-24: Difficulty: _challenging_
 
-Material for MkDocs implements search as part of a [web worker][21]. If you
+Material for MkDocs implements search as part of a [web worker][23]. If you
 want to switch the web worker with your own implementation, e.g. to submit
 search to an external service, you can add a custom JavaScript file to the `docs`
-directory and [override the `config` block][19]:
+directory and [override the `config` block][21]:
 
 ``` html
 {% block config %}
@@ -323,8 +358,8 @@ message format using _discriminated unions_, i.e. through the `type` property
 of the message. See the following interface definitions to learn about the
 message formats:
 
-- [:octicons-file-code-24: `SearchMessage`][22]
-- [:octicons-file-code-24: `SearchIndex` and `SearchResult`][23]
+- [:octicons-file-code-24: `SearchMessage`][24]
+- [:octicons-file-code-24: `SearchIndex` and `SearchResult`][25]
 
 The sequence and direction of messages is rather intuitive:
 
@@ -333,7 +368,7 @@ The sequence and direction of messages is rather intuitive:
 - :octicons-arrow-right-24: `SearchQueryMessage`
 - :octicons-arrow-left-24: `SearchResultMessage`
 
-  [20]: https://github.com/squidfunk/mkdocs-material/blob/master/src/assets/javascripts/integrations/search/worker
-  [21]: https://developer.mozilla.org/en-US/docs/Web/API/Web_Workers_API/Using_web_workers
-  [22]: https://github.com/squidfunk/mkdocs-material/blob/master/src/assets/javascripts/integrations/search/worker/message/index.ts
-  [23]: https://github.com/squidfunk/mkdocs-material/blob/master/src/assets/javascripts/integrations/search/_/index.ts
+  [22]: https://github.com/squidfunk/mkdocs-material/blob/master/src/assets/javascripts/integrations/search/worker
+  [23]: https://developer.mozilla.org/en-US/docs/Web/API/Web_Workers_API/Using_web_workers
+  [24]: https://github.com/squidfunk/mkdocs-material/blob/master/src/assets/javascripts/integrations/search/worker/message/index.ts
+  [25]: https://github.com/squidfunk/mkdocs-material/blob/master/src/assets/javascripts/integrations/search/_/index.ts