7.7 KiB
| 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:
markdown_extensions: # (1)!
- attr_list
- md_in_html
- Note that some of the examples listed below use icons and emojis, which have to be configured separately.
See additional configuration options:
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.
Using card grids
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.
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:
<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>
-
: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:
<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>
-
:material-clock-fast:{ .lg .middle } Set up in 5 minutes
Install
mkdocs-materialwithpipand get up and running in minutes -
:fontawesome-brands-markdown:{ .lg .middle } It's just Markdown
Focus on your content and generate a responsive and searchable static site
-
:material-format-font:{ .lg .middle } Made to measure
Change the colors, fonts, language, icons, logo and more with a few lines
-
:material-scale-balance:{ .lg .middle } Open Source, MIT
Material for MkDocs is licensed under MIT and available on GitHub
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.
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:
<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>
: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
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:
<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>
=== "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