# Grids

Zensical supports arranging 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 your configuration:

```toml
[project.markdown_extensions]
attr_list = {}
md_in_html = {}
```

```yaml
markdown_extensions:
  - attr_list
  - md_in_html
```

> [!NOTE]
>
> **Icons and Emojis**
>
> Note that some of the examples listed below use [icons and emojis](<https://zensical.org/docs/authoring/icons-emojis/index.md>), which have to be [configured separately](<https://zensical.org/docs/authoring/icons-emojis/#configuration>).

See additional configuration options:

- [Attribute Lists](<https://zensical.org/docs/compatibility/markdown/python-markdown/#attribute-lists>)
- [Markdown in HTML](<https://zensical.org/docs/compatibility/markdown/python-markdown/#markdown-in-html>)

## Usage

Grids come in two flavors: [card grids](<#use-card-grids>), which wrap each element in a card that levitates on hover, and [generic grids](<#use-generic-grids>), which allow to arrange arbitrary block elements in a rectangular shape.

### Use 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](<#list-syntax>) and [block syntax](<#block-syntax>), adding support for distinct use cases.

#### List syntax

The list syntax is essentially a shortcut for [card grids](<#use-card-grids>), and consists of an unordered (or ordered) list wrapped by a `div` with both the `grid` and `cards` classes:

Card grid

```html
<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>
```

- **HTML** for content and structure
- **JavaScript** for interactivity
- **CSS** for text running out of boxes
- **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:

Card grid, complex example

```html
<div class="grid cards" markdown>

-   :material-clock-fast:{ .lg .middle } __Set up in 5 minutes__

    ---

    Install [`zensical`](#) 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__

    ---

    Zensical is licensed under MIT and available on [GitHub]

    [:octicons-arrow-right-24: License](#)

</div>
```

- **Set up in 5 minutes**

  ---

  Install [`zensical`](<https://zensical.org>) with [`pip`](<https://zensical.org/docs/get-started/#install-with-pip>) and get up and running in minutes
- **It's just Markdown**

  ---

  Focus on your content and generate a responsive and searchable static site
- **Made to measure**

  ---

  Change the colors, fonts, language, icons, logo, and more with a few lines
- **Open Source, MIT**

  ---

  Zensical is licensed under MIT and available on [GitHub](<https://github.com/zensical/zensical>)

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](<https://zensical.org/docs/setup/navigation/#hide-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](<#use-generic-grids>). Just add the `card` class to any block element inside a `grid`:

Card grid, blocks

```html
<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>
```

**HTML** for content and structure

**JavaScript** for interactivity

**CSS** for text running out of boxes

> **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.

### Use generic grids

Generic grids allow for arranging arbitrary block elements in a grid, including [admonitions](<https://zensical.org/docs/authoring/admonitions/index.md>), [code blocks](<https://zensical.org/docs/authoring/code-blocks/index.md>), [content tabs](<https://zensical.org/docs/authoring/content-tabs/index.md>) and more. Just wrap a set of blocks by using a `div` with the `grid` class:

Generic grid

````html
<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>
````

- Sed sagittis eleifend rutrum
- Donec vitae suscipit est
- Nulla tempor lobortis orci

1. Sed sagittis eleifend rutrum
2. Donec vitae suscipit est
3. Nulla tempor lobortis orci

Content tabs

```text
=== "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
```