README.md

mkdocstrings-crystal

Crystal language doc generator for MkDocs, via mkdocstrings

Introduction

mkdocstrings-crystal allows you to insert API documentation (generated from Crystal's source code and doc comments) as part of any page on a MkDocs site.

See it in action.

To install it, run (possibly in a virtualenv):

pip install mkdocstrings-crystal

Continue to the documentation site.

Usage

With MkDocs, add/merge this base config as your mkdocs.yml:

site_name: My Project

theme:
  name: material

plugins:
  - search
  - mkdocstrings:
      default_handler: crystal

markdown_extensions:
  - pymdownx.highlight
  - deduplicate-toc

Then, in any docs/**/*.md file, you can mention a Crystal identifier alone on a line, after ::::

::: MyClass

::: Other::Class#some_method

::: Foo::CONSTANT

-- and in the output this will be replaced with generated API documentation for it, much like Crystal's own doc generator does.

This, of course, happens as part of a normal MkDocs build process:

mkdocs build  # generate from docs/ into site/
mkdocs serve  # live preview

Continue to the documentation site.