Introduction

Gitian reads your Git repository and turns two things into browsable, connected documentation: annotations in your source code and markdown files in your repo. It renders everything with full Obsidian-flavored markdown — wikilinks, callouts, Mermaid diagrams, KaTeX math, and syntax-highlighted code.

There's nothing to export, sync, or host separately. Your documentation lives in your repo and updates when your code does.

// capture

Capture

Add structured comments to your source code using the @gitian:tag syntax. Gitian detects them and captures the code that follows — a function, a class, a block. The annotation travels with the code: rename it, move it, refactor it, and the annotation stays attached. Built-in categories like note, todo, warning, and security cover common cases, and you can define your own in config.

// structure

Structure

Create markdown files in docs/ or .docs/ directories anywhere in your repo. Gitian discovers them and pairs them with the source files they describe — docs/auth.ts.md documents auth.ts. Write with full Obsidian-flavored markdown: wikilinks connect pages, callouts highlight warnings, and Mermaid diagrams render inline.

// compose

Compose

Pull annotations into your docs with directives. Write {{annotation:@security}} in a markdown file and every security annotation across your repo renders as a live card — code included. Group them, filter by category, or embed a single annotation by ID. The cards update as your code changes. No copy-pasting, no drift.