Reference

Annotations

Structured comments using the @gitian:tag syntax. Gitian detects annotations and captures the code block that follows. Four category kinds control rendering: marker (collapsible task list), inline (card without code), block (card with captured code), and api (ReadMe-style API card with Request / Response payloads). Built-in categories include note, todo, warning, deprecated, security, bug, perf, and api. Annotations support --key=value metadata for IDs, titles, groups, and urgency levels. Use --title="..." to override the displayed heading for a card. The api kind adds two payload-import keys: --request=<id> and --response=<id>. Each points to another annotation's --id; Gitian fetches that annotation and uses its captured code block as the Request or Response panel. The api kind is format-agnostic — gRPC, REST, webhooks, and any other protocol all render the same way.

Full reference: Annotations documentation →

Docs Discovery

Gitian scans your repo for docs/ and .docs/ directories at any level. Markdown files inside are paired with source files by name convention: docs/auth.ts.md documents auth.ts. Directory docs work too — docs/examples.md documents the examples/ directory. All discovered docs merge into a single unified view with cross-file wikilink resolution.

Full reference: Docs discovery documentation →

Directives

Embed annotations in your markdown using {{annotation:...}} directives. Pull in a single annotation by ID ({{annotation:SEC-042}}), all annotations with a tag ({{annotation:@security}}), or an entire group ({{annotation:#auth}}). Directives render as live cards that update when your code changes — no manual syncing.

Full reference: Directives documentation →

Config

Add a .gitian/config.yaml to your repo root to customize behavior. Define custom categories with their own colors, labels, and kinds. Create named groups to organize annotations across files. Set a custom annotation anchor (default: gitian), configure detection tiers, and pin important categories or groups so they surface in the repo dashboard's Needs Attention panel. No config file needed — Gitian works with sensible defaults.

Define optional modules — named areas of your repo (e.g. a service or package). A module binds annotations by directory, group, or an explicit --module= metadata key, and renders as an expandable mini-overview card on the repo overview. Repos with no modules keep the classic overview.

Full reference: Configuration documentation →

Tiered Detection

Beyond @gitian:tag annotations, Gitian can detect two additional tiers. Doc comment tags (@param, @deprecated, @returns, etc.) are detected in /** */ and /// blocks. Bare keywords (TODO, FIXME, HACK) are detected in any comment. Both tiers are opt-in via config or per-file front matter.

Full reference: Detection tiers documentation →

Markdown Features

Gitian renders Obsidian-flavored markdown with full feature support. Wikilinks ([[page]]) connect docs across your repo. Callouts (> [!note]) highlight important information. Mermaid diagrams render inline. KaTeX renders math expressions. Code blocks get full syntax highlighting. Tables, task lists, footnotes, and strikethrough all work as expected.

Full reference: Markdown features documentation →