---
name: "crystal-docs"
section: "1"
platform: "linux"
package: "crystal"
version: "1.22.2-1"
release: "Arch Linux 2026-11-01"
platforms: ["linux"]
url: "https://new.carta.tech/crystal-docs"
---

# crystal-docs(1)

Generate API docs for Crystal code

## NAME

crystal-doc - Generate API docs for Crystal code

## SYNOPSIS

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

## DESCRIPTION

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

## OPTIONS

- **--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).