Gitian supports three tiers of annotation detection, each progressively more automatic.
Tag your code with @gitian or @gitian:<tag> in any comment style. These are the most powerful — they support code capture, metadata, groups, and all tag kinds.
// @gitian:note Requires Node 18+ for crypto.randomUUID()
Enable detect_docs: true in your config to extract annotations from JSDoc and triple-slash comments. Tags like @param, @deprecated, @returns, and @see are automatically recognized.
/** @param id - The user ID to look up */
/** @deprecated Use fetchUserV2 instead */
Doc annotations appear with muted styling to distinguish them from explicit @gitian annotations.
Enable detect_keywords: true to recognize TODO, FIXME, HACK, and other common keywords in any comment style.
// TODO: add error boundary
// FIXME: this breaks on mobile
// HACK: workaround for hydration mismatch
Keywords are mapped to built-in tags — TODO becomes a task marker, FIXME maps to bug, HACK maps to warning, etc.
Both tiers are opt-in via .gitian/config.yaml:
annotations:
detect_docs: true
detect_keywords: true
You can also enable them per-file using YAML front matter in a doc file:
---
detect_docs: true
detect_keywords: true
---