From e96f07ae3d87756bb300f6f513143b9b04b24f6f Mon Sep 17 00:00:00 2001 From: squidfunk Date: Sun, 27 Mar 2022 14:01:30 +0200 Subject: [PATCH] Added documentation for card grids --- docs/reference/code-blocks.md | 2 +- docs/reference/diagrams.md | 2 +- docs/reference/grids.md | 304 +++++++++++++++++++++++ docs/reference/icons-emojis.md | 2 +- docs/setup/extensions/python-markdown.md | 4 + mkdocs.yml | 3 +- 6 files changed, 313 insertions(+), 4 deletions(-) create mode 100644 docs/reference/grids.md diff --git a/docs/reference/code-blocks.md b/docs/reference/code-blocks.md index 5ea72edd5..80e89ca06 100644 --- a/docs/reference/code-blocks.md +++ b/docs/reference/code-blocks.md @@ -1,6 +1,6 @@ --- template: overrides/main.html -icon: material/code-tags +icon: material/code-json --- # Code blocks diff --git a/docs/reference/diagrams.md b/docs/reference/diagrams.md index 5d56a7d63..4a587177f 100644 --- a/docs/reference/diagrams.md +++ b/docs/reference/diagrams.md @@ -1,6 +1,6 @@ --- template: overrides/main.html -icon: material/chart-gantt +icon: material/graph-outline --- # Diagrams diff --git a/docs/reference/grids.md b/docs/reference/grids.md new file mode 100644 index 000000000..3e2cf6610 --- /dev/null +++ b/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" +
+ +- :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? + +
+``` + +
+
+ +- :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? + +
+
+ +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" +
+ +- :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](#) + +
+``` + +
+
+ +- :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] + +
+
+ +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" +
+ +: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? + +
+``` + +
+
+ +: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? + +
+
+ +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" +
+ +=== "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 +``` +
+```` + +
+
+ +=== "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 +``` + +
+
+ + [admonitions]: admonitions.md + [code blocks]: code-blocks.md + [content tabs]: content-tabs.md diff --git a/docs/reference/icons-emojis.md b/docs/reference/icons-emojis.md index 1cdb93100..39163a42e 100644 --- a/docs/reference/icons-emojis.md +++ b/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 diff --git a/docs/setup/extensions/python-markdown.md b/docs/setup/extensions/python-markdown.md index 6324a9cf7..aadbcf7ad 100644 --- a/docs/setup/extensions/python-markdown.md +++ b/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 diff --git a/mkdocs.yml b/mkdocs.yml index ad05c93bf..f845bb822 100755 --- a/mkdocs.yml +++ b/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