Added documentation for card grids

docs/reference/code-blocks.md

@@ -1,6 +1,6 @@
 ---
 template: overrides/main.html
-icon: material/code-tags
+icon: material/code-json
 ---
 
 # Code blocks

docs/reference/diagrams.md

@@ -1,6 +1,6 @@
 ---
 template: overrides/main.html
-icon: material/chart-gantt
+icon: material/graph-outline
 ---
 
 # Diagrams

docs/reference/grids.md

@@ -0,0 +1,304 @@
+---
+template: overrides/main.html
+icon: material/view-grid-plus
+---
+
+# Grids
+
+Material for MkDocs makes it easy to arrange sections into grids, grouping
+blocks that convey similar meaning or are of equal importance. Grids are just
+perfect for building index pages that show a brief overview of a large section
+of your documentation.
+
+## Configuration
+
+This configuration enables the use of grids, allowing to bring blocks of
+identical or different types into a rectangular shape. Add the following lines
+to `mkdocs.yml`:
+
+``` yaml
+markdown_extensions: # (1)!
+  - attr_list
+  - md_in_html
+```
+
+1.  Note that some of the examples listed below use [icons and emojis], which
+    have to be [configured separately].
+
+See additional configuration options:
+
+- [Attribute Lists]
+- [Markdown in HTML]
+
+  [icons and emojis]: icons-emojis.md
+  [configured separately]: icons-emojis.md#configuration
+  [Attribute Lists]: ../setup/extensions/python-markdown.md#attribute-lists
+  [Markdown in HTML]: ../setup/extensions/python-markdown.md#markdown-in-html
+
+## Usage
+
+Grids come in two flavors: [card grids], which wrap each element in a card that
+levitates on hover, and [generic grids], which allow to arrange arbitrary block
+elements in a rectangular shape.
+
+  [card grids]: #using-card-grids
+  [generic grids]: #using-generic-grids
+
+### Using card grids
+
+[:octicons-heart-fill-24:{ .mdx-heart } Insiders][Insiders]{ .mdx-insiders } ·
+[:octicons-tag-24: insiders-4.12.0][Insiders] ·
+:octicons-beaker-24: Experimental
+
+Card grids wrap each grid item with a beautiful hover card that levitates on
+hover. They come in two slightly different syntaxes: [list] and [block syntax],
+adding support for distinct use cases.
+
+  [Insiders]: ../insiders/index.md
+  [list]: #list-syntax
+  [block syntax]: #block-syntax
+
+#### List syntax
+
+The list syntax is essentially a shortcut for [card grids], and consists of an
+unordered (or ordered) list wrapped by a `div` with both, the `grid` and `cards`
+classes:
+
+``` html title="Card grid"
+<div class="grid cards" markdown>
+
+- :fontawesome-brands-html5: __HTML__ for content and structure
+- :fontawesome-brands-js: __JavaScript__ for interactivity
+- :fontawesome-brands-css3: __CSS__ for text running out of boxes
+- :fontawesome-brands-internet-explorer: __Internet Explorer__ ... huh?
+
+</div>
+```
+
+<div class="result" markdown>
+  <div class="grid cards" markdown>
+
+- :fontawesome-brands-html5: __HTML__ for content and structure
+- :fontawesome-brands-js: __JavaScript__ for interactivity
+- :fontawesome-brands-css3: __CSS__ for text running out of boxes
+- :fontawesome-brands-internet-explorer: __Internet Explorer__ ... huh?
+
+  </div>
+</div>
+
+List elements can contain arbitrary Markdown, as long as the surrounding `div`
+defines the `markdown` attribute. Following is a more complex example, which
+includes icons and links:
+
+``` html title="Grid with cards, complex example"
+<div class="grid cards" markdown>
+
+-   :material-clock-fast:{ .lg .middle } __Set up in 5 minutes__
+
+    ---
+
+    Install [`mkdocs-material`](#) with [`pip`](#) and get up
+    and running in minutes
+
+    [:octicons-arrow-right-24: Getting started](#)
+
+-   :fontawesome-brands-markdown:{ .lg .middle } __It's just Markdown__
+
+    ---
+
+    Focus on your content and generate a responsive and searchable static site
+
+    [:octicons-arrow-right-24: Reference](#)
+
+-   :material-format-font:{ .lg .middle } __Made to measure__
+
+    ---
+
+    Change the colors, fonts, language, icons, logo and more with a few lines
+
+    [:octicons-arrow-right-24: Customization](#)
+
+-   :material-scale-balance:{ .lg .middle } __Open Source, MIT__
+
+    ---
+
+    Material for MkDocs is licensed under MIT and available on [GitHub]
+
+    [:octicons-arrow-right-24: License](#)
+
+</div>
+```
+
+<div class="result" markdown>
+  <div class="grid cards" markdown>
+
+-   :material-clock-fast:{ .lg .middle } __Set up in 5 minutes__
+
+    ---
+
+    Install [`mkdocs-material`][mkdocs-material] with [`pip`][pip] and get up
+    and running in minutes
+
+    [:octicons-arrow-right-24: Getting started][getting started]
+
+-   :fontawesome-brands-markdown:{ .lg .middle } __It's just Markdown__
+
+    ---
+
+    Focus on your content and generate a responsive and searchable static site
+
+    [:octicons-arrow-right-24: Reference][reference]
+
+-   :material-format-font:{ .lg .middle } __Made to measure__
+
+    ---
+
+    Change the colors, fonts, language, icons, logo and more with a few lines
+
+    [:octicons-arrow-right-24: Customization][customization]
+
+-   :material-scale-balance:{ .lg .middle } __Open Source, MIT__
+
+    ---
+
+    Material for MkDocs is licensed under MIT and available on [GitHub]
+
+    [:octicons-arrow-right-24: License][license]
+
+  </div>
+</div>
+
+If there's insufficient space to render grid items next to each other, the items
+will stretch to the full width of the viewport, e.g. on mobile viewports. If
+there's more space available, grids will render in items of 3 and more, e.g.
+when [hiding both sidebars].
+
+  [mkdocs-material]: https://pypistats.org/packages/mkdocs-material
+  [pip]: ../getting-started.md#with-pip
+  [getting started]: ../getting-started.md
+  [reference]: ../reference/index.md
+  [customization]: ../customization.md
+  [license]: ../license.md
+  [GitHub]: https://github.com/squidfunk/mkdocs-material
+  [hiding both sidebars]: ../setup/setting-up-navigation.md#hiding-the-sidebars
+
+#### Block syntax
+
+The block syntax allows for arranging cards in grids __together with other
+elements__, as explained in the section on [generic grids]. Just add the `card`
+class to any block element inside a `grid`:
+
+``` html title="Card grid, blocks"
+<div class="grid" markdown>
+
+:fontawesome-brands-html5: __HTML__ for content and structure
+{ .card }
+
+:fontawesome-brands-js: __JavaScript__ for interactivity
+{ .card }
+
+:fontawesome-brands-css3: __CSS__ for text running out of boxes
+{ .card }
+
+> :fontawesome-brands-internet-explorer: __Internet Explorer__ ... huh?
+
+</div>
+```
+
+<div class="result" markdown>
+  <div class="grid" markdown>
+
+:fontawesome-brands-html5: __HTML__ for content and structure
+{ .card }
+
+:fontawesome-brands-js: __JavaScript__ for interactivity
+{ .card }
+
+:fontawesome-brands-css3: __CSS__ for text running out of boxes
+{ .card }
+
+> :fontawesome-brands-internet-explorer: __Internet Explorer__ ... huh?
+
+  </div>
+</div>
+
+While this syntax may seem unnecessarily verbose at first, the previous example
+shows how card grids can now be mixed with other elements that will also stretch
+to the grid.
+
+### Using generic grids
+
+[:octicons-heart-fill-24:{ .mdx-heart } Insiders][Insiders]{ .mdx-insiders } ·
+[:octicons-tag-24: insiders-4.12.0][Insiders] ·
+:octicons-beaker-24: Experimental
+
+Generic grids allow for arranging arbitrary block elements in a grid, including
+[admonitions], [code blocks], [content tabs] and more. Just wrap a set of blocks
+by using a `div` with the `grid` class:
+
+```` html title="Generic grid"
+<div class="grid" markdown>
+
+=== "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
+
+``` title="Content tabs"
+=== "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
+```
+</div>
+````
+
+<div class="result" markdown>
+  <div class="grid" markdown>
+
+=== "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
+
+``` title="Content tabs"
+=== "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
+```
+
+  </div>
+</div>
+
+  [admonitions]: admonitions.md
+  [code blocks]: code-blocks.md
+  [content tabs]: content-tabs.md

docs/reference/icons-emojis.md

@@ -3,7 +3,7 @@ template: overrides/main.html
 icon: material/emoticon-happy-outline
 ---
 
-# Icons + Emojis
+# Icons, Emojis
 
 One of the best features of Material for MkDocs is the possibility to use [more
 than 8,000 icons][icon search] and thousands of emojis in your project 

docs/setup/extensions/python-markdown.md

@@ -82,6 +82,7 @@ markdown_extensions:
 No configuration options are available. See reference for usage:
 
 - [Using annotations]
+- [Using grids]
 - [Adding buttons]
 - [Adding icons with colors]
 - [Image alignment]
@@ -90,6 +91,7 @@ No configuration options are available. See reference for usage:
   [Attribute Lists]: https://python-markdown.github.io/extensions/attr_list/
   [Attribute Lists support]: https://github.com/squidfunk/mkdocs-material/releases/tag/0.1.0
   [Attribute Lists limitations]: https://python-markdown.github.io/extensions/attr_list/#limitations
+  [Using grids]: ../../reference/grids.md#using-grids
   [Adding buttons]: ../../reference/buttons.md#adding-buttons
   [Adding icons with colors]: ../../reference/buttons.md#with-colors
   [Image alignment]: ../../reference/images.md#image-alignment
@@ -200,11 +202,13 @@ markdown_extensions:
 No configuration options are available. See reference for usage:
 
 - [Using annotations]
+- [Using grids]
 - [Image captions]
 
   [Markdown in HTML]: https://python-markdown.github.io/extensions/md_in_html/
   [Markdown in HTML support]: https://github.com/squidfunk/mkdocs-material/releases/tag/0.1.0
   [Using annotations]: ../../reference/annotations.md#usage
+  [Using grids]: ../../reference/grids.md#usage
   [Image captions]: ../../reference/images.md#image-captions
 
 ### Table of Contents

mkdocs.yml

@@ -204,7 +204,8 @@ nav:
     - Diagrams: reference/diagrams.md
     - Footnotes: reference/footnotes.md
     - Formatting: reference/formatting.md
-    - Icons + Emojis: reference/icons-emojis.md
+    - Grids: reference/grids.md
+    - Icons, Emojis: reference/icons-emojis.md
     - Images: reference/images.md
     - Lists: reference/lists.md
     - MathJax: reference/mathjax.md