Quickstart

What is Gitian

Gitian reads your repository and surfaces two things: annotations (structured comments in your code) and docs (markdown files in docs/ or .docs/ directories). It renders them with full Obsidian-flavored markdown support — wikilinks, callouts, Mermaid diagrams, KaTeX math, and syntax-highlighted code.

Connect your repo

1. Sign in with your GitHub account.
2. Install the Gitian GitHub App on the repo (or org) you want to document.
3. Your repo appears on your dashboard — click it to start browsing.

Public repos work without installing the app — just navigate to them directly.

Add your first annotation

Add a comment to any source file using the @gitian:tag syntax:

// @gitian:note
// This module handles OAuth token refresh.
// Tokens are cached in memory and refreshed
// 5 minutes before expiry.
export async function refreshToken(token: Token) {
  // ...
}

Commit and push. Gitian picks it up automatically — the annotation appears in the file view with the captured code block.

Built-in tags: note, todo, warning, deprecated, security, bug, perf. You can also define custom tags in .gitian/config.yaml.

Document a source file

Create a markdown file in a docs/ directory with the same name as a source file plus .md. Gitian automatically links them:

---
title: Authentication
---

# auth.ts

Handles OAuth token lifecycle — refresh, caching,
and expiry. See [[getting-started]] for setup.

> [!warning]
> Tokens are cached in memory. Restarts clear the cache.

This doc appears alongside auth.ts in the file viewer. Full Obsidian-flavored markdown is supported — wikilinks, callouts, Mermaid diagrams, KaTeX math, and more.

Bring it together with directives

Pull annotations into your docs using {{annotation:...}} directives. They render as live cards that stay in sync with your code:

## Key annotations

Embed a single annotation by ID:
{{annotation:token-refresh}}

Or pull in every annotation tagged security:
{{annotation:@security}}

Or everything in the auth group:
{{annotation:#auth}}

Annotations live in your code. Docs give them structure. Directives compose them into pages that update as your code changes — no copy-pasting, no drift.

See it live

Browse the demo app to see annotations, docs, and all markdown features rendered in a real repository. The demo also serves as the full configuration reference — every config field, tag kind, and feature is documented there using Gitian itself.