Quick-start guide

This assumes you already have some project in Crystal, say, a file src/foo.cr.

src/foo.cr

module Foo
  # Description of *Bar*
  class Bar
    # Description of *f*
    def f(x : Int32)
    end
  end

  # Description of *g*
  #
  # See also: `Bar#f`
  def g(bar : Bar)
  end
end

Hosting on GitHub is also assumed, though that's easy to adapt.

We'll be working from the project's root directory (the one that contains src).

View the final file layout

Dependencies

The dependencies that we'll be using can be installed like this:

$ pip install mkdocs-material mkdocstrings-crystal

This assumes you have Python installed, with pip available.

Tip

You might want to install these in a virtualenv (i.e. localized just to this project).

And check out how to manage Python dependencies long-term.

Base config

Let's configure MkDocs with mkdocstrings-crystal. Add/merge this config as your mkdocs.yml:

mkdocs.yml

site_name: My Project
site_url: https://username.github.io/my-project/
repo_url: https://github.com/username/my-project
edit_uri: blob/master/docs/

theme:
  name: material
  icon:
    repo: fontawesome/brands/github

extra_css:
  - css/mkdocstrings.css

plugins:
  - search
  - mkdocstrings:
      default_handler: crystal
      watch: [src]

markdown_extensions:
  - pymdownx.highlight
  - pymdownx.magiclink
  - pymdownx.saneheaders
  - pymdownx.superfences
  - deduplicate-toc
  - toc:
      permalink: "#"

Why configure like this

theme: material

material is the only supported MkDocs theme.

repo_url and icon

Link back to your repository nicely. See more.

extra_css

Don't forget to copy and include the recommended styles.

mkdocstrings: default_handler: crystal

Activate the upstream mkdocstrings plugin and tell it to collect items from Crystal, not Python, by default.

watch: [src]

Watch a directory for auto-reload. Assuming the sources are under src/.

pymdownx.* extensions

Python-Markdown is an "old-school" Markdown parser, and these extensions bring the defaults more in line with what people are used to now.

deduplicate-toc extension

This is actually an integral part of mkdocstrings-crystal. Read more.

Add an API doc page

docs/api.md

# module Foo

The main class in our library is `Bar`.

::: Foo::Bar

---

There is also a helper function:

::: Foo#g

Add a normal page

docs/index.md

# Introduction

Welcome to my project!

See [the API documentation](api.md). Make sure to check out [Foo#g(bar)][].

We linked directly to an identifier here, and mkdocstrings knows which page it's on and automatically links that. See: identifier linking syntax.

View the site

That's it -- we're ready!

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

Next steps

If you find that you have too many classes and you don't want to manually create files with callouts to them, there are ways to automate it, and good examples are in the migration-oriented guide.

Otherwise, you're encouraged to curate per-topic pages with your API items. See "Manually curated docs page" in Showcase for examples.

And you'll probably want to set up a navigation config anyway.