Skip to content


"deduplicate-toc" extension#

For most usages it is recommended to enable the "deduplicate-toc" Markdown extension, which comes bundled with mkdocstrings-crystal. It de-duplicates consecutive items that have the same title in the table of contents. This is important because Crystal can have multiple overloads of a method but in the ToC only their names are shown.

"callouts" extension#

mkdocstrings-crystal auto-enables the "callouts" extension for Markdown (only within doc comments' content), so you can use that syntax instead of the common "admonition" extension's syntax.

# Frobs the bar
# DEPRECATED: Use `baz` instead.
def frob(bar)

You can also enable that extension for the whole site:


  - callouts

Admonition styles#

In addition to the usual admonition styles, mkdocstrings-crystal injects styling for the Material theme to enable the following admonition kinds, used in Crystal documentation:


TODO: !!! todo


NOTE: !!! note


BUG: !!! bug


FIXME: !!! fixme


DEPRECATED: !!! deprecated


OPTIMIZE: !!! optimize

Both the default styles and the extra styles work with both the "callouts" extension (write them in all-uppercase) and the "admonition" extension (write them in all-lowercase).

Support for MkDocs "macros" plugin#

Without support, you have to access the doc root as

{% set crystal = config.plugins['mkdocstrings'].get_handler('crystal').root %}

But instead you can use the convenience pluglet shipped with mkdocstrings-crystal to have such a crystal object available in every page without the above assignment.


  - macros:
        - mkdocstrings_handlers.crystal.macros

Then you can dynamically generate Markdown based on introspecting Crystal's type tree. For example, instead of writing this in Markdown:

These are the built-in mogrifier implementations:

* [Foo][MyModule::Mogrifiers::Foo]
* [Bar][MyModule::Mogrifiers::Bar]
* [Baz][MyModule::Mogrifiers::Baz]

you can just write:

These are the built-in mogrifier implementations:

{% for typ in crystal.lookup('MyModule::Mogrifiers').types %}
  - [{{}}][{{typ.abs_id}}]
{% endfor %}

Browse the API exposed by the root DocType.

Support for MkDocs "gen-files" plugin#

There's no special support, these just work well together.

The plugin exposes the MkDocs config, and from there you can get to the doc root:

root = config.plugins['mkdocstrings'].get_handler('crystal').root

Browse the API exposed by the root DocType.

From there, you can generate Markdown files based on introspecting Crystal's type tree. This usage is described in the guide.