Skip to content

HoneyDev Docs

MkDocs

MkDocs

Personal documentation to help me remember how to use MkDocs Material and all the various extensions that I have added to it for the purpose of my personal documentation.

Admonitions

Enabling admonitions

In the mkdocs.yml file, add this to enable the Admonition extension through the documentation:

YAML
markdown_extensions:
  - admonition

Admonition icons

Each of the supported admonition types has a distinct icon, which can be changed to any icon bundled with the theme, or even a custom icon. Add the following lines to mkdocs.yml:

YAML
theme:
  icon:
    admonition:
      <type>: <icon>

Supported types

Customization

You can customize the appearance of admonitions via an additional style sheet. Below is an example that restyles admonitions to an earlier version used by MkDocs:

docs/stylesheets/extra.cssmkdocs.yml

CSS
.md-typeset .admonition,
.md-typeset details {
  border-width: 0;
  border-left-width: 4px;
}

YAML
extra_css:
    - stylesheets/extra.css

By this same logic, you can create custom admonitions:

docs/stylesheets/extra.cssmkdocs.yml

CSS
:root {
    --md-admonition-icon--pied-piper: url('...');
}
.md-typeset .admonition.pied-piper,
.md-typeset details.pied-piper {
    border-color: rgb(43, 155, 70);
}
.md-typeset .pied-piper > .admonition-title,
.md-typeset .pied-piper > summary {
    background-color: rgba(43, 155, 70, 0.1);
}
.md-typeset .pied-piper > .admonition-title::before,
.md-typeset .pied-piper > summary::before {
    background-color: rgb(43, 155, 70);
    -webkit-mask-image: var(--md-admonition-icon--pied-piper);
            mask-image: var(--md-admonition-icon--pied-piper);
}

YAML
extra_css:
    - stylesheets/extra.css

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:

Admonition
!!! 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.

If no type qualifier is included, it fallbacks to the default type of note.

Changing the title

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

Admonition with custom title
!!! 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.

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 Details is enabled and an admonition block is started with ??? instead of !!!, the admonition is rendered as an expandable block with a small toggle indicator on the right side. Alternatively, you can use ???+ to create a collapsible block that renders expanded:

DefaultExpanded

Collapsible admonition
??? 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.

Collapsible admonition
???+ 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 the left using only the inline modifier:

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 admonition
!!! note inline end
    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.

Critic Markup

The Critic extension allows for the usage of Critic Markup to highlight added, ~~deleted~~, or otherwise modified sections in a document, i.e. for tracking changes in Markdown syntax.

Syntax

There are five types of Critic marks that allow you to successfully copy edit in plain text/Markdown:

Mark	Syntax
Addition	`{\++Addition++\}`
~~Deletion~~	`{\--Deletion--\}`
~~text~~Substitution	`{\~~text~>Substitution~~\}`
Comment	`{\>>Comment<<\}`
Highlight	`{\==Highlight==\}`

Syntax issue

Due to the nature of the Critic Markup and inline code, the above syntax is modified to be readable. The actual syntax requires the removal of all \ characters.

Keys Syntax

When Keys is enabled, keyboard keys can be rendered with a simple syntax. Consult the Python Markdown Extensions documentation to learn about all available shortcodes.

Keyboard keys
++ctrl+alt+del++

Ctrl+Alt+Del

Tabs

Enabling tabs

In the mkdocs.yml file, add this to enable the Tabbed extension throughout the documentation:

YAML
markdown_extensions:
  - pymdownx.tabbed:
      alternate_style: true

Note

You must include alternate_style: true for tabs to work.

Using tabs

Tabs start with === to signify a tab followed by a quoted title. Consecutive tabs are grouped into a tab set.

Markdown
=== "Tab 1"
    Markdown **content**.

    Multiple paragraphs.

=== "Tab 2"
    More Markdown **content**.

    - list item a
    - list item b

Tab 1Tab 2

Markdown content.

Multiple paragraphs.

More Markdown content.

list item a
list item b

Note

The indentation matters. Not indenting a paragraph intended to be within a tab breaks it.

In the rare case that you want to follow two separate tab sets right after each other, you can explicitly mark the start of a new tab set with !.

Markdown
=== "Tab 1"
    Markdown **content**.

    Multiple paragraphs.

=== "Tab 2"
    More Markdown **content**.

    - list item a
    - list item b

===! "Tab A"
    Different tab set.

=== "Tab B"
    ```
    More content.
    ```

Tab 1Tab 2

Markdown content.

Multiple paragraphs.

More Markdown content.

list item a
list item b

Tab ATab B

Different tab set.

Text Only
More content.

Tab Select

If you'd like to force a tab to be selected, simply use ===+, otherwise the first tab will be selected by default.

Markdown
=== "Not Me"
    Markdown **content**.

    Multiple paragraphs.

===+ "Select Me"
    More Markdown **content**.

    - list item a
    - list item b

=== "Not Me Either"
    Another Tab

Not MeSelect MeNot Me Either

Markdown content.

Multiple paragraphs.

More Markdown content.

list item a
list item b

Another Tab