Documentation you can trace to a tag

CrystalDocs builds and hosts API documentation for published Crystal shards. Every page is generated from the source of a tagged release, and rendered here by us.

How a page gets here

  1. A release is tagged

    The builder watches for tagged releases on the source repository. There is no upload step and no dashboard to log into.

  2. The compiler describes the code

    We run the Crystal compiler's own documentation generator against that tag in a sandboxed build, and keep one machine-readable document per version.

  3. We render the pages

    Types, namespaces, signatures and READMEs are laid out by our templates, from that document. The version in the URL is the version you are reading.

crystal docs --format=json

Why we do not serve the compiler's HTML

The compiler can emit a finished HTML tree as well as a machine-readable document. We deliberately do not serve that tree, for two reasons.

It ships its own theme and stylesheet, which cannot be reconciled with ours, so the documentation would look like a different site from the one you navigated in.

More importantly, it is markup written by whoever published the shard. A doc comment can contain any markup its author typed, and a README is Markdown, which permits inline HTML. Serving either of those raw would hand shard authors script execution on this origin. Both are treated as untrusted input and sanitised before they reach a page.

The standard library is not a special case

Crystal's standard library is published through the same pipeline as every shard, under the package name crystal. It is built the same way, stored the same way and rendered by the same templates.

That is what lets a signature mentioning a core type link somewhere useful instead of sending you off to another site: the page it points at is one of ours.

Browse the standard library

Getting your own shard documented

Tag a release and push the tag. The builder picks it up from there, and the version appears once the build finishes. There is nothing to upload and nothing to configure.

git tag -a v1.0.0 -m "Release v1.0.0"
git push --tags
Browse all documentation