CRYSTAL-DOC(1) Crystal Compiler Command Line Reference Guide CRYSTAL-DOC(1)

crystal-doc - Generate API docs for Crystal code

crystal build [options] [programfile] [--] [arguments]

Generate documentation from comments using a subset of markdown. The output is saved in html format on the created docs/ folder. More information about documentation conventions can be found at https://crystal-lang.org/docs/conventions/documenting_code.html.

--project-name NAME

Set the project name. The default value is extracted from shard.yml if available.

In case no default can be found, this option is mandatory.

--project-version VERSION

Set the project version. The default value is extracted from current git commit or shard.yml if available.

In case no default can be found, this option is mandatory.

--json-config-url URL

Set the URL pointing to a config file (used for discovering versions).

--source-refname REFNAME

Set source refname (e.g. git tag, commit hash). The default value is extracted from current git commit if available.

If this option is missing and can’t be automatically determined, the generator can’t produce source code links.

--source-url-pattern URL

Set URL pattern for source code links. The default value is extracted from git remotes ("origin" or first one) if available and the provider’s URL pattern is recognized.

Supported replacement tags:

%{refname}

commit reference

%{path}

path to source file inside the repository

%{filename}

basename of the source file

%{line}

line number

If this option is missing and can’t be automatically determined, the generator can’t produce source code links.

-o DIR, --output DIR

Set the output directory (default: ./docs).

-b URL, --canonical-base-url URL

Indicate the preferred URL with rel="canonical" link element.

-b URL, --sitemap-base-url URL

Set the sitemap base URL. Sitemap will only be generated when this option is set.

--sitemap-priority PRIO

Set the priority assigned to sitemap entries (default: 1.0).

--sitemap-changefreq FREQ

Set the changefreq assigned to sitemap entries (default: never).
2026-07-23 crystal 1.21.0