Extras

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

example.cr

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

You can also enable that extension for the whole site:

mkdocs.yml

markdown_extensions:
  - 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: !!! todo

Note

NOTE: !!! note

Bug

BUG: !!! bug

Fixme

FIXME: !!! fixme

Deprecated

DEPRECATED: !!! deprecated

Optimize

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.

mkdocs.yml

plugins:
  - macros:
      modules:
        - 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.name}}][{{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.