Reference
Feature overview with links to the full documentation in the demo repository.
Annotations
Structured comments using the @gitian:tag syntax. Gitian detects annotations and captures the code block that follows. Three tag kinds control rendering: marker (collapsible task list), inline (card without code), and block (card with captured code). Built-in tags include note, todo, warning, deprecated, security, bug, and perf. Annotations support --key=value metadata for IDs, groups, and urgency levels.
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 tags 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 tags or groups to the repo dashboard. No config file needed — Gitian works with sensible defaults.
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 →