Added documentation for linking of content tabs

CHANGELOG

@@ -1,3 +1,7 @@
+mkdocs-material-7.1.5+insiders.2.9.0 (2021-05-23)
+
+  * Added support for linking of content tabs
+
 mkdocs-material-7.1.5 (2021-05-19)
 
   * Fixed #2655: Details breaking page margins on print

docs/insiders/changelog.md

@@ -6,6 +6,10 @@ template: overrides/main.html
 
 ## Material for MkDocs Insiders
 
+### 2.9.0 <small>_ May 23, 2021</small>
+
+- Added support for linking of content tabs
+
 ### 2.8.0 <small>_ May 12, 2021</small>
 
 - Added support for boosting pages in search

docs/insiders/index.md

@@ -111,6 +111,7 @@ The following features are currently exclusively available to sponsors:
 
 <div class="mdx-columns" markdown="1">
 
+- [x] [Linking content tabs :material-new-box:][32]
 - [x] [Boosting pages in search :material-new-box:][30]
 - [x] [Tags (with search integration) :material-new-box:][29]
 - [x] [Stay on page when switching versions][28]
@@ -199,18 +200,19 @@ the public for general availability.
 #### $ 8,000 – Scotch Bonnet
 
 - [x] [Custom admonition icons][31]
-- [ ] Table of contents shows which sections have search results
+- [x] [Linking content tabs][32]
 - [ ] List of last searches
 
   [31]: ../reference/admonitions.md#changing-the-icons
+  [32]: ../reference/content-tabs.md#linking-content-tabs
 
 #### Future
 
-- [ ] [Material for MkDocs Live Edit][32]
+- [ ] [Material for MkDocs Live Edit][33]
 - [ ] New layouts and styles
 - [ ] Code block palette toggle
 
-  [32]: https://twitter.com/squidfunk/status/1338252230265360391
+  [33]: https://twitter.com/squidfunk/status/1338252230265360391
 
 ### Goals completed
 
@@ -265,10 +267,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][33] only in CI, as you don't want to expose
+recommended to [install Insiders][34] only in CI, as you don't want to expose
 your `GH_TOKEN` to users.
 
-  [33]: ../publishing-your-site.md#github-pages
+  [34]: ../publishing-your-site.md#github-pages
 
 ### Terms
 
@@ -277,7 +279,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][34]. However, we kindly ask you to respect the following
+by the [MIT license][35]. However, we kindly ask you to respect the following
 guidelines:
 
 - Please __don't distribute the source code__ of Insiders. You may freely use
@@ -288,7 +290,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][35].
+  [GitHub deletes private forks][36].
 
-  [34]: ../license.md
-  [35]: https://docs.github.com/en/github/setting-up-and-managing-your-github-user-account/removing-a-collaborator-from-a-personal-repository
+  [35]: ../license.md
+  [36]: https://docs.github.com/en/github/setting-up-and-managing-your-github-user-account/removing-a-collaborator-from-a-personal-repository

docs/reference/content-tabs.md

@@ -6,7 +6,8 @@ template: overrides/main.html
 
 Sometimes, it's desirable to group alternative content under different tabs,
 e.g. when describing how to access an API from different languages or
-environments. Material for MkDocs allows for beautiful and functional tabs, grouping code blocks and other content.
+environments. Material for MkDocs allows for beautiful and functional tabs,
+grouping code blocks and other content.
 
 ## Configuration
 
@@ -133,11 +134,45 @@ _Result_:
     2. Donec vitae suscipit est
     3. Nulla tempor lobortis orci
 
+### Linking content tabs
+
+[:octicons-file-code-24: Source][5] ·
+:octicons-beaker-24: Experimental ·
+[:octicons-heart-fill-24:{ .mdx-heart } Insiders only][5]{ .mdx-insiders }
+
+When _linking_ is enabled, all content tabs on a page will be linked and show
+the same active tab when the user clicks on a label. Add the following lines
+to `mkdocs.yml`:
+
+``` yaml
+theme:
+  features:
+    - content.tabs.link
+```
+
+Content tabs are linked based on their label, not offset. This means that all
+tabs with the same label will be activated when a user clicks a content tab
+regardless of order inside a container. Furthermore, this feature is fully
+integrated with [instant loading][6] and persisted across page loads.
+
+=== "With linking"
+
+    [![With linking][7]][7]
+
+=== "Without linking"
+
+    [![Without linking][8]][8]
+
+  [5]: ../insiders/index.md
+  [6]: ../setup/setting-up-navigation.md#instant-loading
+  [7]: ../assets/screenshots/content-tabs-link.png
+  [8]: ../assets/screenshots/content-tabs.png
+
 ### Embedded content
 
-When [SuperFences][5] is enabled, content tabs can contain arbitrary nested
+When [SuperFences][9] is enabled, content tabs can contain arbitrary nested
 content, including further content tabs, and can be nested in other blocks like
-[admonitions][6], [details][7] or blockquotes:
+[admonitions][10], [details][11] or blockquotes:
 
 _Example_:
 
@@ -213,6 +248,6 @@ _Result_:
         2. Donec vitae suscipit est
         3. Nulla tempor lobortis orci
 
-  [5]: #superfences
-  [6]: admonitions.md
-  [7]: admonitions.md#details
+  [9]: #superfences
+  [10]: admonitions.md
+  [11]: admonitions.md#details