Style Guide¶

The following Style Guide is for Material for MkDocs and can be found here

Feel free to use these below, for your documentation.

Note

Please look at the Protocols and blueprints first, on how to document here

Admonitions¶

Basic Usage¶

Admonitions follow a simple syntax: a block starts with !!!, followed by a single keyword used as a type qualifier. The content of the block follows on the next line, indented by four spaces:

ExampleCode

Note

Lorem ipsum dolor sit amet, consectetur adipiscing elit. Nulla et euismod nulla. Curabitur feugiat, tortor non consequat finibus, justo purus auctor massa, nec semper lorem quam in massa.

!!! note

    Lorem ipsum dolor sit amet, consectetur adipiscing elit. Nulla et euismod
    nulla. Curabitur feugiat, tortor non consequat finibus, justo purus auctor
    massa, nec semper lorem quam in massa.

Changing the Title¶

By default, the title will equal the type qualifier in titlecase. However, it can be changed by adding a quoted string containing valid Markdown (including links, formatting, ...) after the type qualifier:

ExampleCode

Phasellus posuere in sem ut cursus

Lorem ipsum dolor sit amet, consectetur adipiscing elit. Nulla et euismod nulla. Curabitur feugiat, tortor non consequat finibus, justo purus auctor massa, nec semper lorem quam in massa.

!!! note "Phasellus posuere in sem ut cursus"

    Lorem ipsum dolor sit amet, consectetur adipiscing elit. Nulla et euismod
    nulla. Curabitur feugiat, tortor non consequat finibus, justo purus auctor
    massa, nec semper lorem quam in massa.

Collapsible blocks¶

When block is started with ??? instead of !!!, the admonition is rendered as a collapsible block with a small toggle on the right side:

ExampleCode

Note

Lorem ipsum dolor sit amet, consectetur adipiscing elit. Nulla et euismod nulla. Curabitur feugiat, tortor non consequat finibus, justo purus auctor massa, nec semper lorem quam in massa.

??? note

    Lorem ipsum dolor sit amet, consectetur adipiscing elit. Nulla et euismod
    nulla. Curabitur feugiat, tortor non consequat finibus, justo purus auctor
    massa, nec semper lorem quam in massa.

Inline blocks¶

Admonitions can also be rendered as inline blocks (e.g., for sidebars), placing them to the right using the inline + end modifiers, or to the left using only the inline modifier:

Use inline end to align to the right (left for rtl languages).
Use inline to align to the left (right for rtl languages).

ExampleCode

Lorem ipsum

Lorem ipsum dolor sit amet, consectetur adipiscing elit. Nulla et euismod nulla. Curabitur feugiat, tortor non consequat finibus, justo purus auctor massa, nec semper lorem quam in massa.

Lorem ipsum 

!!! info inline end "Lorem ipsum"

    Lorem ipsum dolor sit amet, consectetur
    adipiscing elit. Nulla et euismod nulla.
    Curabitur feugiat, tortor non consequat
    finibus, justo purus auctor massa, nec
    semper lorem quam in massa.

Types¶

Following is a list of type qualifiers provided, whereas the default type, and thus fallback for unknown type qualifiers, is note

List of types

Annotations¶

Link to official docs

Basic Usage¶

Annotations consist of two parts: a marker, which can be placed anywhere in a block marked with the annotate class, and content located in a list below the block containing the marker:

ExampleCode

Lorem ipsum dolor sit amet, (1) consectetur adipiscing elit.

I'm an annotation! I can contain code, formatted text, images, ... basically anything that can be expressed in Markdown.

Lorem ipsum dolor sit amet, (1) consectetur adipiscing elit.
{ .annotate }

1.  :man_raising_hand: I'm an annotation! I can contain `code`, __formatted
    text__, images, ... basically anything that can be expressed in Markdown.

Nested Usage¶

Annotations can be nested inside annotations by adding the annotate class to the list item hosting the annotation content, repeating the process:

ExampleCode

Lorem ipsum dolor sit amet, (1) consectetur adipiscing elit.

I'm an annotation! (1)
1. I'm an annotation as well!

Lorem ipsum dolor sit amet, (1) consectetur adipiscing elit.
{ .annotate }

1.  :man_raising_hand: I'm an annotation! (1)
    { .annotate }

    1.  :woman_raising_hand: I'm an annotation as well!

In Admonitions¶

The titles and bodies of admonitions can also host annotations by adding the annotate modifier after the type qualifier, which is similar to how inline blocks work:

ExampleCode

Phasellus posuere in sem ut cursus (1)

Lorem ipsum dolor sit amet, (2) consectetur adipiscing elit. Nulla et euismod nulla. Curabitur feugiat, tortor non consequat finibus, justo purus auctor massa, nec semper lorem quam in massa.

I'm an annotation!
I'm an annotation as well!

!!! note annotate "Phasellus posuere in sem ut cursus (1)"

    Lorem ipsum dolor sit amet, (2) consectetur adipiscing elit. Nulla et
    euismod nulla. Curabitur feugiat, tortor non consequat finibus, justo
    purus auctor massa, nec semper lorem quam in massa.

1.  :man_raising_hand: I'm an annotation!
2.  :woman_raising_hand: I'm an annotation as well!

In Content Tabs¶

Content tabs can host annotations by adding the annotate class to the block of a dedicated content tab (and not to the container, which is not supported):

ExampleCode

Tab 1Tab 2

Lorem ipsum dolor sit amet, (1) consectetur adipiscing elit.

I'm an annotation!

Phasellus posuere in sem ut cursus (1)

I'm an annotation as well!

=== "Tab 1"

    Lorem ipsum dolor sit amet, (1) consectetur adipiscing elit.
    { .annotate }

    1.  :man_raising_hand: I'm an annotation!

=== "Tab 2"

    Phasellus posuere in sem ut cursus (1)
    { .annotate }

    1.  :woman_raising_hand: I'm an annotation as well!

Code Blocks¶

Link to official docs

Basic Usage¶

Code blocks must be enclosed with two separate lines containing three backticks. To add syntax highlighting to those blocks, add the language shortcode directly after the opening block. See the list of available lexers to find the shortcode for a given language.

Code with Annotations¶

Code annotations offer a comfortable and friendly way to attach arbitrary content to specific sections of code blocks by adding numeric markers in block and inline comments in the language of the code block.

They can be placed anywhere in a code block where a comment for the language of the block can be placed, e.g. for JavaScript in // ... and /* ... */, for YAML in # ..., etc

ExampleCode

theme:
features:
    - content.code.annotate # (1)

I'm a code annotation! I can contain code, formatted text, images, ... basically anything that can be written in Markdown.

``` yaml 
theme: 
    features: 
        - content.code.annotate

I'm a code annotation! I can contain code, formatted text, images, ... basically anything that can be written in Markdown. ```

And if you wish to strip the comment characters surrounding a code annotation, simply add an ! after the closing parenthesis of the code annotation:

ExampleCode

# (1)!

Look ma, less line noise!

``` yaml 
# (1)!

Look ma, less line noise! ```

Adding a title¶

In order to provide additional context, a custom title can be added to a code block by using the title="<custom title>" option directly after the shortcode, e.g. to display the name of a file:

ExampleCode

bubble_sort.py

def bubble_sort(items):
    for i in range(len(items)):
        for j in range(len(items) - 1 - i):
            if items[j] > items[j + 1]:
                items[j], items[j + 1] = items[j + 1], items[j]

``` py title="bubble_sort.py"
def bubble_sort(items):
    for i in range(len(items)):
        for j in range(len(items) - 1 - i):
            if items[j] > items[j + 1]:
                items[j], items[j + 1] = items[j + 1], items[j] 
    ```

Adding Line Numbers¶

Line numbers can be added to a code block by using the linenums="<start>" option directly after the shortcode, whereas <start> represents the starting line number. A code block can start from a line number other than 1, which allows to split large code blocks for readability:

ExampleCode

def bubble_sort(items):
    for i in range(len(items)):
        for j in range(len(items) - 1 - i):
            if items[j] > items[j + 1]:
                items[j], items[j + 1] = items[j + 1], items[j]

``` py linenums="1"
def bubble_sort(items):
    for i in range(len(items)):
        for j in range(len(items) - 1 - i):
            if items[j] > items[j + 1]:
                items[j], items[j + 1] = items[j + 1], items[j] 
    ```

Highlighting Specific Lines¶

Specific lines can be highlighted by passing the line numbers to the hl_lines argument placed right after the language shortcode. Note that line counts start at 1, regardless of the starting line number specified as part of linenums:

with highlighted LINES..

ExampleCode

def bubble_sort(items):
    for i in range(len(items)):
        for j in range(len(items) - 1 - i):
            if items[j] > items[j + 1]:
                items[j], items[j + 1] = items[j + 1], items[j]

``` py hl_lines="2 3"
def bubble_sort(items):
    for i in range(len(items)):
        for j in range(len(items) - 1 - i):
            if items[j] > items[j + 1]:
                items[j], items[j + 1] = items[j + 1], items[j]
    ```

with highlighted RANGE..

ExampleCode

def bubble_sort(items):
    for i in range(len(items)):
        for j in range(len(items) - 1 - i):
            if items[j] > items[j + 1]:
                items[j], items[j + 1] = items[j + 1], items[j]

``` py hl_lines="3-5"
def bubble_sort(items):
    for i in range(len(items)):
        for j in range(len(items) - 1 - i):
            if items[j] > items[j + 1]:
                items[j], items[j + 1] = items[j + 1], items[j]
    ```

Highlighting Inline Code Blocks¶

Syntax highlighting can be applied to inline code blocks by prefixing them with a shebang, i.e. #!, directly followed by the corresponding language shortcode.

ExampleCode

The range() function is used to generate a sequence of numbers.

The `#!python range()` function is used to generate a sequence of numbers.

Content tabs¶

Link to official docs

Basic Usage¶

In order to link to content tabs and share them more easily, an anchor link is automatically added to each content tab, which you can copy via right click or open in a new tab.

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:

ExampleCode

CC++

#include <stdio.h>

int main(void) {
printf("Hello world!\n");
return 0;
}

#include <iostream>

int main(void) {
std::cout << "Hello world!" << std::endl;
return 0;
}

=== "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:

ExampleCode

Unordered listOrdered list

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

Sed sagittis eleifend rutrum
Donec vitae suscipit est
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

Embedded content¶

Content tabs can contain arbitrary nested content, including further content tabs, and can be nested in other blocks like admonitions or blockquotes:

ExampleCode

Example

Unordered ListOrdered List

* 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

!!! example

    === "Unordered List"

        ``` markdown
        * Sed sagittis eleifend rutrum
        * Donec vitae suscipit est
        * Nulla tempor lobortis orci
        ```

    === "Ordered List"

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

Data tables¶

Link to official docs

Basic Usage¶

Data tables can be used at any position in your project documentation and can contain arbitrary Markdown, including inline code blocks, as well as icons and emojis:

ExampleCode

Method	Description
`GET`	Fetch resource
`PUT`	Update resource
`DELETE`	Delete resource

| Method      | Description                          |
| ----------- | ------------------------------------ |
| `GET`       | :material-check:     Fetch resource  |
| `PUT`       | :material-check-all: Update resource |
| `DELETE`    | :material-close:     Delete resource |

Column alignment¶

If you want to align a specific column to the left, center or right, you can use the regular Markdown syntax placing : characters at the beginning and/or end of the divider.

with Center..

ExampleCode

Method	Description
`GET`	Fetch resource
`PUT`	Update resource
`DELETE`	Delete resource

| Method      | Description                          |
| :---------: | :----------------------------------: |
| `GET`       | :material-check:     Fetch resource  |
| `PUT`       | :material-check-all: Update resource |
| `DELETE`    | :material-close:     Delete resource |

with Left..

ExampleCode

Method	Description
`GET`	Fetch resource
`PUT`	Update resource
`DELETE`	Delete resource

| Method      | Description                          |
| :---------- | :----------------------------------- |
| `GET`       | :material-check:     Fetch resource  |
| `PUT`       | :material-check-all: Update resource |
| `DELETE`    | :material-close:     Delete resource |

Table Sort¶

Data tables are sortable and note that it provides alternative comparison implementations like numbers, filesizes, dates and month names. See the tablesort documentation for more information.

Diagrams¶

Link to official docs

Material for MkDocs integrates with Mermaid.js, a very popular and flexible solution for drawing diagrams.

Note

In case of doubt, you may want to test your diagram in the Mermaid Live Editor

Note, however, that the Mermaid Live Editor does not support loose mode (with HTML code in the mermaid code).

Using flowcharts¶

Flowcharts are diagrams that represent workflows or processes. The steps are rendered as nodes of various kinds and are connected by edges, describing the necessary order of steps:

Using sequence diagrams¶

Sequence diagrams describe a specific scenario as sequential interactions between multiple objects or actors, including the messages that are exchanged between those actors:

ExampleCode

sequenceDiagram
autonumber
Alice->>John: Hello John, how are you?
loop Healthcheck
    John->>John: Fight against hypochondria
end
Note right of John: Rational thoughts!
John-->>Alice: Great!
John->>Bob: How about you?
Bob-->>John: Jolly good!

``` mermaid
sequenceDiagram
autonumber
Alice->>John: Hello John, how are you?
loop Healthcheck
    John->>John: Fight against hypochondria
end
Note right of John: Rational thoughts!
John-->>Alice: Great!
John->>Bob: How about you?
Bob-->>John: Jolly good!
    ```

Using state diagrams¶

State diagrams are a great tool to describe the behavior of a system, decomposing it into a finite number of states, and transitions between those states:

ExampleCode

stateDiagram-v2
state fork_state <<fork>>
    [*] --> fork_state
    fork_state --> State2
    fork_state --> State3

    state join_state <<join>>
    State2 --> join_state
    State3 --> join_state
    join_state --> State4
    State4 --> [*]

``` mermaid
stateDiagram-v2
state fork_state <<fork>>
    [*] --> fork_state
    fork_state --> State2
    fork_state --> State3

    state join_state <<join>>
    State2 --> join_state
    State3 --> join_state
    join_state --> State4
    State4 --> [*]
    ```

Using class diagrams¶

Class diagrams are central to object oriented programming, describing the structure of a system by modelling entities as classes and relationships between them:

ExampleCode

classDiagram
Person <|-- Student
Person <|-- Professor
Person : +String name
Person : +String phoneNumber
Person : +String emailAddress
Person: +purchaseParkingPass()
Address "1" <-- "0..1" Person:lives at
class Student{
    +int studentNumber
    +int averageMark
    +isEligibleToEnrol()
    +getSeminarsTaken()
}
class Professor{
    +int salary
}
class Address{
    +String street
    +String city
    +String state
    +int postalCode
    +String country
    -validate()
    +outputAsLabel()  
}

``` mermaid
classDiagram
Person <|-- Student
Person <|-- Professor
Person : +String name
Person : +String phoneNumber
Person : +String emailAddress
Person: +purchaseParkingPass()
Address "1" <-- "0..1" Person:lives at
class Student{
    +int studentNumber
    +int averageMark
    +isEligibleToEnrol()
    +getSeminarsTaken()
}
class Professor{
    +int salary
}
class Address{
    +String street
    +String city
    +String state
    +int postalCode
    +String country
    -validate()
    +outputAsLabel()  
}
    ```

Using entity-relationship diagrams¶

An entity-relationship diagram is composed of entity types and specifies relationships that exist between entities. It describes inter-related things in a specific domain of knowledge:

ExampleCode

erDiagram
CUSTOMER ||--o{ ORDER : places
ORDER ||--|{ LINE-ITEM : contains
LINE-ITEM {
    string name
    int pricePerUnit
}
CUSTOMER }|..|{ DELIVERY-ADDRESS : uses

``` mermaid
erDiagram
CUSTOMER ||--o{ ORDER : places
ORDER ||--|{ LINE-ITEM : contains
LINE-ITEM {
    string name
    int pricePerUnit
}
CUSTOMER }|..|{ DELIVERY-ADDRESS : uses
    ```

Other diagram types¶

Besides the diagram types listed above, Mermaid.js provides support for other diagram types but they are not officially supported by Material for MkDocs.

Footnotes¶

Link to official docs

Basic Usage¶

A footnote reference must be enclosed in square brackets and must start with a caret ^, directly followed by an arbitrary identifier, which is similar to the standard Markdown link syntax.

ExampleCode

Lorem ipsum¹ dolor sit amet, consectetur adipiscing elit.²

Lorem ipsum[^1] dolor sit amet, consectetur adipiscing elit.[^2]

Adding Footnote Content¶

The footnote content must be declared with the same identifier as the reference. It can be inserted at an arbitrary position in the document and is always rendered at the bottom of the page. Furthermore, a backlink to the footnote reference is automatically added.

on a single line..

Short footnotes can be written on the same line:

ExampleCode

Jump to Footnote

[^1]: Lorem ipsum dolor sit amet, consectetur adipiscing elit.

on multiple lines..

Paragraphs can be written on the next line and must be indented by four spaces:

ExampleCode

Jump to Footnote

[^2]:
    Lorem ipsum dolor sit amet, consectetur adipiscing elit. Nulla et euismod
    nulla. Curabitur feugiat, tortor non consequat finibus, justo purus auctor
    massa, nec semper lorem quam in massa.

Formatting¶

Link to official docs

Basic Usage¶

Highlighting changes adds the ability to highlight suggested changes, as well as add inline comments to a document:

ExampleCode

Text can be ~~deleted~~ and replacement text added. This can also be combined into ~~one~~a single operation. Highlighting is also possible and comments can be added inline .

Formatting can also be applied to blocks by putting the opening and closing tags on separate lines and adding new lines between the tags and the content.

Remove the space from the curly brachets for it to work ! 

Text can be { --deleted-- } and replacement text { ++added++ }. This can also be
combined into { ~~one~ >a single~~ } operation. { == Highlighting== } is also
possible and comments can be added inline.

`{ ==`

Formatting can also be applied to blocks by putting the opening and closing
tags on separate lines and adding new lines between the tags and the content.

`==}`

Definition Lists¶

With Definition Lists, lists of arbitrary key-value pairs, e.g. the parameters of functions or modules, can be enumerated with a simple syntax:

ExampleCode

Lorem ipsum dolor sit amet

Sed sagittis eleifend rutrum. Donec vitae suscipit est. Nullam tempus tellus non sem sollicitudin, quis rutrum leo facilisis.

Cras arcu libero

Aliquam metus eros, pretium sed nulla venenatis, faucibus auctor ex. Proin ut eros sed sapien ullamcorper consequat. Nunc ligula ante.

Duis mollis est eget nibh volutpat, fermentum aliquet dui mollis. Nam vulputate tincidunt fringilla. Nullam dignissim ultrices urna non auctor.

`Lorem ipsum dolor sit amet`

:   Sed sagittis eleifend rutrum. Donec vitae suscipit est. Nullam tempus
    tellus non sem sollicitudin, quis rutrum leo facilisis.

`Cras arcu libero`

:   Aliquam metus eros, pretium sed nulla venenatis, faucibus auctor ex. Proin
    ut eros sed sapien ullamcorper consequat. Nunc ligula ante.

    Duis mollis est eget nibh volutpat, fermentum aliquet dui mollis.
    Nam vulputate tincidunt fringilla.
    Nullam dignissim ultrices urna non auctor.

Tasks and Task List¶

With Tasklist, unordered list items can be prefixed with [ ] to render an unchecked checkbox or [x] to render a checked checkbox, allowing for the definition of task lists:

ExampleCode

Lorem ipsum dolor sit amet, consectetur adipiscing elit
Vestibulum convallis sit amet nisi a tincidunt
- In hac habitasse platea dictumst
- In scelerisque nibh non dolor mollis congue sed et metus
- Praesent sed risus massa
Aenean pretium efficitur erat, donec pharetra, ligula non scelerisque

- [x] Lorem ipsum dolor sit amet, consectetur adipiscing elit
- [ ] Vestibulum convallis sit amet nisi a tincidunt
    * [x] In hac habitasse platea dictumst
    * [x] In scelerisque nibh non dolor mollis congue sed et metus
    * [ ] Praesent sed risus massa
- [ ] Aenean pretium efficitur erat, donec pharetra, ligula non scelerisque

Highlighting text¶

Text can be highlighted with a simple syntax:

ExampleCode

Addition
Comment
Highlight
~~Deletion~~
This was marked (highlight)
This was inserted (underline)
~~This was deleted (strikethrough)~~

some blue text

- { ++Addition++ }
- { >>Comment<< }
- Highlight { == == }{ >> << }
- { --Deletion-- }
- ==This was marked (highlight)==
- ^^This was inserted (underline)^^
- ~~This was deleted (strikethrough)~~

<span style="color:blue">some *blue* text</span>

Sub- and superscripts¶

Text can be sub- and superscripted with a simple syntax:

ExampleCode

H₂O
A^TA

- H~2~O
- A^T^A

Adding keyboard keys¶

Keyboard keys can be rendered with a simple syntax. Consult the Python Markdown Extensions documentation to learn about all available shortcodes:

ExampleCode

Ctrl+Alt+Del

++ctrl+alt+del++

Grids¶

Link to official docs

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:

ExampleCode

HTML for content and structure
JavaScript for interactivity
CSS for text running out of boxes
Internet Explorer ... huh?

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

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:

ExampleCode

Set up in 5 minutes

Install mkdocs-material with pip and get up and running in minutes

Getting started
It's just Markdown

Focus on your content and generate a responsive and searchable static site

Reference
Made to measure

Change the colors, fonts, language, icons, logo and more with a few lines

Customization
Open Source, MIT

Material for MkDocs is licensed under MIT and available on [GitHub]

License

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

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:

ExampleCode

HTML for content and structure

JavaScript for interactivity

CSS for text running out of boxes

Internet Explorer ... huh?

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

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:

ExampleCode

Unordered listOrdered list

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

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

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

Icons, Emojis¶

Link to official docs

One of the best features of Material for MkDocs is the possibility to use more than 10,000 icons and thousands of emojis with practically zero additional effort.

Find a emoji or icon here

Using emojis¶

Emojis can be integrated in Markdown by putting the shortcode of the emoji between two colons

ExampleCode

:smile:

Using icons¶

Icons can be used similar to emojis, by referencing a valid path to any icon bundled with the theme, which are located in the .icons directory, and replacing / with -

ExampleCode

:fontawesome-regular-face-laugh-wink:

Images¶

Link to official docs

Image alignment¶

Images can be aligned by adding the respective alignment directions via the align attribute, i.e. align=left or align=right

Image, aligned to left..

ExampleCode

Image title

![Image title](https://dummyimage.com/600x400/eee/aaa){ align=left }

Image, aligned to right..

ExampleCode

Image title

![Image title](https://dummyimage.com/600x400/eee/aaa){ align=right }

Image captions¶

Sadly, the Markdown syntax doesn't provide native support for image captions, but it's always possible to use with literal figure and figcaption tags:

ExampleCode

<figure markdown="span">
    ![Image title](https://dummyimage.com/600x400/){ width="300" }
    <figcaption>Image caption</figcaption>
</figure>

Lists¶

Link to official docs

Unordered lists can be written by prefixing a line with a -, * or + list marker, all of which can be used interchangeably. Furthermore, all flavors of lists can be nested inside each other:

ExampleCode

Nulla et rhoncus turpis. Mauris ultricies elementum leo. Duis efficitur accumsan nibh eu mattis. Vivamus tempus velit eros, porttitor placerat nibh lacinia sed. Aenean in finibus diam.
- Duis mollis est eget nibh volutpat, fermentum aliquet dui mollis.
- Nam vulputate tincidunt fringilla.
- Nullam dignissim ultrices urna non auctor.

- Nulla et rhoncus turpis. Mauris ultricies elementum leo. Duis efficitur
accumsan nibh eu mattis. Vivamus tempus velit eros, porttitor placerat nibh
lacinia sed. Aenean in finibus diam.

    * Duis mollis est eget nibh volutpat, fermentum aliquet dui mollis.
    * Nam vulputate tincidunt fringilla.
    * Nullam dignissim ultrices urna non auctor.

Ordered lists must start with a number immediately followed by a dot. The numbers do not need to be consecutive and can be all set to 1., as they will be re-numbered when rendered:

ExampleCode

Vivamus id mi enim. Integer id turpis sapien. Ut condimentum lobortis sagittis. Aliquam purus tellus, faucibus eget urna at, iaculis venenatis nulla. Vivamus a pharetra leo.
1. Vivamus venenatis porttitor tortor sit amet rutrum. Pellentesque aliquet quam enim, eu volutpat urna rutrum a. Nam vehicula nunc mauris, a ultricies libero efficitur sed.
2. Morbi eget dapibus felis. Vivamus venenatis porttitor tortor sit amet rutrum. Pellentesque aliquet quam enim, eu volutpat urna rutrum a.
  1. Mauris dictum mi lacus
  2. Ut sit amet placerat ante
  3. Suspendisse ac eros arcu

1.  Vivamus id mi enim. Integer id turpis sapien. Ut condimentum lobortis
    sagittis. Aliquam purus tellus, faucibus eget urna at, iaculis venenatis
    nulla. Vivamus a pharetra leo.

    1.  Vivamus venenatis porttitor tortor sit amet rutrum. Pellentesque aliquet
        quam enim, eu volutpat urna rutrum a. Nam vehicula nunc mauris, a
        ultricies libero efficitur sed.

    2.  Morbi eget dapibus felis. Vivamus venenatis porttitor tortor sit amet
        rutrum. Pellentesque aliquet quam enim, eu volutpat urna rutrum a.

        1.  Mauris dictum mi lacus
        2.  Ut sit amet placerat ante
        3.  Suspendisse ac eros arcu

Definition lists¶

Lists of arbitrary key-value pairs, e.g. the parameters of functions or modules, can be enumerated with a simple syntax:

ExampleCode

Lorem ipsum dolor sit amet

Sed sagittis eleifend rutrum. Donec vitae suscipit est. Nullam tempus tellus non sem sollicitudin, quis rutrum leo facilisis.

Cras arcu libero

Aliquam metus eros, pretium sed nulla venenatis, faucibus auctor ex. Proin ut eros sed sapien ullamcorper consequat. Nunc ligula ante.

Duis mollis est eget nibh volutpat, fermentum aliquet dui mollis. Nam vulputate tincidunt fringilla. Nullam dignissim ultrices urna non auctor.

`Lorem ipsum dolor sit amet`

:   Sed sagittis eleifend rutrum. Donec vitae suscipit est. Nullam tempus
    tellus non sem sollicitudin, quis rutrum leo facilisis.

`Cras arcu libero`

:   Aliquam metus eros, pretium sed nulla venenatis, faucibus auctor ex. Proin
    ut eros sed sapien ullamcorper consequat. Nunc ligula ante.

    Duis mollis est eget nibh volutpat, fermentum aliquet dui mollis.
    Nam vulputate tincidunt fringilla.
    Nullam dignissim ultrices urna non auctor.

Task lists¶

Unordered list items can be prefixed with [ ] to render an unchecked checkbox or [x] to render a checked checkbox, allowing for the definition of task lists:

ExampleCode

Lorem ipsum dolor sit amet, consectetur adipiscing elit
Vestibulum convallis sit amet nisi a tincidunt
- In hac habitasse platea dictumst
- In scelerisque nibh non dolor mollis congue sed et metus
- Praesent sed risus massa
Aenean pretium efficitur erat, donec pharetra, ligula non scelerisque

- [x] Lorem ipsum dolor sit amet, consectetur adipiscing elit
- [ ] Vestibulum convallis sit amet nisi a tincidunt
    * [x] In hac habitasse platea dictumst
    * [x] In scelerisque nibh non dolor mollis congue sed et metus
    * [ ] Praesent sed risus massa
- [ ] Aenean pretium efficitur erat, donec pharetra, ligula non scelerisque

Tooltips¶

Link to official docs

Add a tooltip to a link with the following lines:

ExampleCode

Hover me

[Hover me](https://example.com "I'm a tooltip!")

Tooltips can also be added to link references:

ExampleCode

Hover me

[Hover me][example]

[example]: https://example.com "I'm a tooltip!"

For all other elements, a title can be added by :

ExampleCode

:material-information-outline:{ title="Important information" }

Adding abbreviations¶

Abbreviations can be defined by using a special syntax similar to URLs and footnotes, starting with a * and immediately followed by the term or acronym to be associated in square brackets:

ExampleCode

The HTML specification is maintained by the W3C.

The HTML specification is maintained by the W3C.

*[HTML]: Hyper Text Markup Language
*[W3C]: World Wide Web Consortium

Lorem ipsum dolor sit amet, consectetur adipiscing elit. ↩
Lorem ipsum dolor sit amet, consectetur adipiscing elit. Nulla et euismod nulla. Curabitur feugiat, tortor non consequat finibus, justo purus auctor massa, nec semper lorem quam in massa. ↩