Added docs on content tabs

docs/data-privacy.md

@@ -32,7 +32,7 @@ the `fonts` block.
 
   [2]: guides/changing-the-fonts.md
   [3]: https://github.com/google/fonts/issues/1495
-  [4]: customization.md#overriding-template-blocks
+  [4]: customization.md#overriding-blocks
 
 ### Google Analytics and Disqus
 

docs/guides/changing-the-fonts.md

@@ -6,8 +6,8 @@ template: overrides/main.html
 
 Material for MkDocs makes it easy to change the typeface of your project
 documentation, as it directly integrates with [Google Fonts][1]. Alternatively,
-fonts can be custom-loaded if self-hosting is preferred or another destination
-should be used.
+fonts can be custom-loaded if self-hosting is preferred for data privacy reasons
+or another destination should be used.
 
   [1]: https://fonts.google.com
 

docs/guides/changing-the-language.md

@@ -83,7 +83,8 @@ The following languages are supported:
 
 Some languages, like Arabic or Japanese, need dedicated stemmers for search to
 work properly. Material for MkDocs relies on [lunr-languages][3] to provide this 
-functionality. See the [setting up site search][4] guide for more information.
+functionality. See the guide detailing how to [set up site search][4] for
+more information.
 
   [2]: https://github.com/squidfunk/mkdocs-material/blob/master/src/assets/javascripts/integrations/search/worker/main/index.ts#L49-L69
   [3]: https://github.com/MihaiValentin/lunr-languages

docs/guides/setting-up-navigation.md

@@ -35,7 +35,7 @@ intact in-between document switches.
   [1]: https://github.com/squidfunk/mkdocs-material/blob/master/src/assets/javascripts/integrations/instant/index.ts
   [2]: https://developer.mozilla.org/en-US/docs/Web/API/XMLHttpRequest
 
-### Tabs navigation
+### Navigation tabs
 
 [:octicons-file-code-24: Source][3] · :octicons-unlock-24: Feature flag
 
@@ -97,7 +97,7 @@ used to render these pages.
 
 [:octicons-file-code-24: Source][5] · [:octicons-workflow-24: Extension][6]
 
-The [Table of Contents][7] extension, which is part of the standard Markdown
+The [Table of contents][7] extension, which is part of the standard Markdown
 library, provides some options that are supported by Material for MkDocs to
 customize its appearance:
 

docs/writing/admonitions.md

@@ -5,9 +5,9 @@ template: overrides/main.html
 # Admonitions
 
 Admonitions, also know as _call-outs_, are an excellent choice for including
-side content into your project documentation minimally interrupting the document
-flow. Material for MkDocs provides several types of admonitions and allows for
-the inclusion and nesting of arbitrary content.
+side content without significantly interrupting the document flow. Material for
+MkDocs provides several different types of admonitions and allows for the
+inclusion and nesting of arbitrary content.
 
 ## Configuration
 

docs/writing/code-blocks.md

@@ -211,7 +211,7 @@ def bubble_sort(items):
 
 _Result_:
 
-``` python linenums="1" hl_lines="2 3"
+``` python hl_lines="2 3"
 def bubble_sort(items):
     for i in range(len(items)):
         for j in range(len(items) - 1 - i):
@@ -223,7 +223,7 @@ def bubble_sort(items):
 
 When [InlineHilite][13] is enabled, inline code blocks can be highlighted by
 prefixing them with a shebang-like sequence, i.e. `#!`, directly followed by
-the language short name.
+the [language short name][12].
 
 _Example_:
 

docs/writing/content-tabs.md

@@ -0,0 +1,165 @@
+---
+template: overrides/main.html
+---
+
+# Content tabs
+
+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 tabbed
+content, including code blocks or body copy.
+
+## Configuration
+
+### Tabbed
+
+[:octicons-file-code-24: Source][1] · [:octicons-workflow-24: Extension][2]
+
+The [Tabbed][2] extension, which is part of [Python Markdown Extensions][3],
+integrates with Material for MkDocs and can be enabled from `mkdocs.yml`:
+
+``` yaml
+markdown_extensions:
+  - pymdownx.tabbed
+```
+
+  [1]: https://github.com/squidfunk/mkdocs-material/blob/master/src/assets/stylesheets/extensions/pymdown/_tabbed.scss
+  [2]: https://facelessuser.github.io/pymdown-extensions/extensions/tabbed/
+  [3]: https://facelessuser.github.io/pymdown-extensions/
+
+## Usage
+
+### Grouping code blocks
+
+Code blocks are one of the primary targets to be grouped, and can be considered
+a special case of content tabs, as tabs with a single code block are always
+rendered without horizontal spacing.
+
+_Example_:
+
+```
+=== "C"
+
+    ``` c
+    #include <stdio.h>
+
+    int main(void) {
+      printf("Hello world!\n");
+      return 0;
+    }
+    ```
+
+=== "C++"
+
+    ``` c++
+    #include <iostream>
+
+    int main(void) {
+      std::cout << "Hello world!" << std::endl;
+      return 0;
+    }
+    ```
+```
+
+_Result_:
+
+=== "C"
+
+    ``` c
+    #include <stdio.h>
+
+    int main(void) {
+      printf("Hello world!\n");
+      return 0;
+    }
+    ```
+
+=== "C++"
+
+    ``` c++
+    #include <iostream>
+
+    int main(void) {
+      std::cout << "Hello world!" << std::endl;
+      return 0;
+    }
+    ```
+
+### Grouping other content
+
+When a content tab contains more than one code block, it is rendered with
+horizontal spacing. Vertical spacing is never added, but can be achieved
+by nesting tabs in other blocks.
+
+_Example_:
+
+```
+=== "Unordered list"
+
+    - Sed sagittis eleifend rutrum
+    - Donec vitae suscipit est
+    - Nulla tempor lobortis orci
+
+=== "Ordered list"
+
+    1. Sed sagittis eleifend rutrum
+    2. Donec vitae suscipit est
+    3. Nulla tempor lobortis orci
+```
+
+_Result_:
+
+=== "Unordered list"
+
+    - Sed sagittis eleifend rutrum
+    - Donec vitae suscipit est
+    - Nulla tempor lobortis orci
+
+=== "Ordered list"
+
+    1. Sed sagittis eleifend rutrum
+    2. Donec vitae suscipit est
+    3. Nulla tempor lobortis orci
+
+### Embedded content
+
+Content tabs can contain arbitrary nested content, including further content
+tabs, and can be nested in other blocks like [admonitions][4], [details][5] or 
+blockquotes:
+
+!!! quote ""
+
+    === "Unordered Lists"
+
+        _Example_:
+
+        ``` markdown
+        - Sed sagittis eleifend rutrum
+        - Donec vitae suscipit est
+        - Nulla tempor lobortis orci
+        ```
+
+        _Result_:
+
+        - Sed sagittis eleifend rutrum
+        - Donec vitae suscipit est
+        - Nulla tempor lobortis orci
+
+    === "Ordered Lists"
+
+        _Example_:
+
+        ``` markdown
+        1. Sed sagittis eleifend rutrum
+        2. Donec vitae suscipit est
+        3. Nulla tempor lobortis orci
+        ```
+
+        _Result_:
+
+        1. Sed sagittis eleifend rutrum
+        2. Donec vitae suscipit est
+        3. Nulla tempor lobortis orci
+
+  [4]: admonitions.md
+  [5]: admonitions.md#details

material/assets/manifest.json

@@ -5,8 +5,8 @@
   "assets/javascripts/vendor.js.map": "assets/javascripts/vendor.877163d5.min.js.map",
   "assets/javascripts/worker/search.js": "assets/javascripts/worker/search.a68abb33.min.js",
   "assets/javascripts/worker/search.js.map": "assets/javascripts/worker/search.a68abb33.min.js.map",
-  "assets/stylesheets/main.css": "assets/stylesheets/main.5a89d9ca.min.css",
-  "assets/stylesheets/main.css.map": "assets/stylesheets/main.5a89d9ca.min.css.map",
+  "assets/stylesheets/main.css": "assets/stylesheets/main.1b6dc5da.min.css",
+  "assets/stylesheets/main.css.map": "assets/stylesheets/main.1b6dc5da.min.css.map",
   "assets/stylesheets/overrides.css": "assets/stylesheets/overrides.0ad0ad40.min.css",
   "assets/stylesheets/overrides.css.map": "assets/stylesheets/overrides.0ad0ad40.min.css.map",
   "assets/stylesheets/palette.css": "assets/stylesheets/palette.87445083.min.css",

material/base.html

@@ -41,7 +41,7 @@
       {% endif %}
     {% endblock %}
     {% block styles %}
-      <link rel="stylesheet" href="{{ 'assets/stylesheets/main.5a89d9ca.min.css' | url }}">
+      <link rel="stylesheet" href="{{ 'assets/stylesheets/main.1b6dc5da.min.css' | url }}">
       {% if palette.scheme or palette.primary or palette.accent %}
         <link rel="stylesheet" href="{{ 'assets/stylesheets/palette.87445083.min.css' | url }}">
       {% endif %}

mkdocs.yml

@@ -129,11 +129,12 @@ nav:
     - Creating your site: creating-your-site.md
     - Publishing your site: publishing-your-site.md
     - Customization: customization.md
-    - Troubleshooting: troubleshooting.md
+    #- Troubleshooting: troubleshooting.md
     - Data privacy: data-privacy.md
   - Writing:
     - Admonitions: writing/admonitions.md
     - Code blocks: writing/code-blocks.md
+    - Content tabs: writing/content-tabs.md
     - Footnotes: writing/footnotes.md
   - Guides:
     - Changing colors: guides/changing-colors.md

src/assets/stylesheets/base/_typeset.scss

@@ -52,7 +52,7 @@ kbd {
 // ----------------------------------------------------------------------------
 
 // Content that is typeset - if possible, all margins, paddings and font sizes
-// should be set in ems, so nested blocks (e.g. Admonition) render correctly,
+// should be set in ems, so nested blocks (e.g. admonitions) render correctly,
 // except headlines that should only appear on the top level and need to have
 // consistent spacing due to layout constraints.
 .md-typeset {

src/assets/stylesheets/extensions/_admonition.scss

@@ -107,6 +107,11 @@ $admonitions: (
     .md-typeset__table {
       padding: 0 px2rem(12px);
     }
+
+    // Tabbed block container is the only child
+    > .tabbed-set:only-child {
+      margin-top: 0;
+    }
   }
 
   // Admonition title
@@ -144,7 +149,7 @@ $admonitions: (
       }
     }
 
-    // Reset code inside Admonition titles
+    // Reset code inside admonition titles
     code {
       margin: initial;
       padding: initial;
@@ -153,6 +158,11 @@ $admonitions: (
       border-radius: initial;
       box-shadow: none;
     }
+
+    // Tabbed block container is the last child
+    + .tabbed-set:last-child {
+      margin-top: 0;
+    }
   }
 }