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

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 tags like note, todo, warning, and security cover common cases, and you can define your own in config.

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

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 tag, or embed a single annotation by ID. The cards update as your code changes. No copy-pasting, no drift.