Your code is already documented

Documentation that lives with your code

Your codebase is already full of TODOs, warnings, and explanations buried in comments. Add @gitian and they become structured, browsable documentation — no wiki migration, no new tools, no starting from scratch.

Explore demo
my-project / src / lib / auth
Docs3
Source
Important

Session tokens are encrypted with AES-256-GCM. The key is derived from SESSION_SECRET.

This namespace manages authenticated sessions. See [[CONTRIBUTING#Auth Flow]] for the full sequence diagram.
typescriptL42–48
42export async function getSession(req: Request) {
43  const cookie = req.headers.get("cookie");
44  if (!cookie) return null;
45  return await decrypt(cookie, key);
46}

Capture

@gitian in a comment. That's the entire migration.

Structure

docs/ directories, file pairing, wikilinks — your repo becomes the docs.

Compose

Directives pull live annotations into markdown. Code changes, docs update.

Documentation shouldn't be a second job

Every workaround has a why. Every edge case has a story. Gitian keeps those stories where they belong — next to the code.

No more context switching

You understand code while you're writing it. Five minutes later in a wiki, you're reconstructing from memory. Gitian keeps docs in the same file, same commit, same thought.

No more drift

Same commit, same branch, same PR. When code changes, the docs beside it change too. Delete a function and its documentation goes with it.

No more ghost pages

Delete a module and its wiki page lives on forever, misleading everyone who finds it. In Gitian, docs are the repo — nothing outlives its source.

The migration

Your code is already documented. You just can't see it.

Every codebase is full of invisible documentation — TODOs, deprecation warnings, explanations buried in comment blocks. They're useful the moment you read them, then forgotten the moment you scroll past.

Before
23// TODO: batch these to avoid N+1 queries
24async function syncInventory(items) {
25 // WARNING: vendor API has 30s timeout
26 for (const item of items) {
27 // Retry logic handles transient 503s
28 await pushToVendor(item);
29 }
30}
After
Batch these to avoid N+1 queries:24
@gitian:warningVendor API has 30s timeout
async function syncInventory(items) { ... }
@gitianRetry logic handles transient 503s
await pushToVendor(item);

Add @gitian to the comments you've already written. That's it. That's the migration.

Features

Rich docs, right in the browser

Wikilinks, callouts, diagrams, math, and more — rendered directly from your GitHub repos. GitLab and self-hosted git support coming soon.

Source
1// @gitian Validates user input
2export function validate(input) {
3  // @gitian:todo Add rate limiting
4  return input.isValid;
5}
6// @gitian:deprecated Use validate() instead
7function check(v) { ... }
Rendered
@gitianValidates user input
export function validate(input) { ... }
Add rate limiting
@gitian:deprecatedUse validate() instead
function check(v) { ... }

Code Annotations

Tag functions with @gitian for annotated docs, or use sub-tags like @gitian:todo and @gitian:deprecated for semantic categorization. Add #global to surface annotations on the dashboard. Also picks up your existing @param and TODO comments automatically.

Markdown
{{annotation:@todo}}
Batch N+1 queries in syncInventoryinventory.ts:24
Add rate limiting to validate()validation.ts:3
Migrate legacy auth to OAuth2auth.ts:87

Directives

Pull live annotations into markdown with {{annotation:@todo}}. Code changes, docs update automatically.

Markdown
See [[Auth Flow]] for details
Rendered
See Auth Flow for details

Wikilinks

Navigate between docs with [[wikilinks]] and aliases, resolved across your repository.

Tip

Use environment variables for secrets

⚠ Warning

This will invalidate all active sessions

Callouts

Rich callout blocks with proper icons, colors, and nesting support.

Client
Auth
Database

Mermaid Diagrams

Flowcharts, sequence diagrams, and ERDs render inline.

$$E = mc^2$$
↓
E = mc2
Σ

KaTeX Math

Inline and block math with full LaTeX support via KaTeX.

VS
VS Code
Ze
Zed
Ob
Obsidian
Coming soon

Editor Integrations

Plugins for VS Code, Zed, and Obsidian are coming soon — write and preview annotations without leaving your editor.

14  const data = await fetch(url);
15  const json = await data.json();
16  return validate(json);
Copy link to line 15
Copy GitHub permalink
Copy line 15

Line Permalinks

Click line numbers to select, right-click for a context menu — copy Gitian links, GitHub permalinks, or source code.

Gi
acme/api
github.com/acme/api

GitHub Integration

Install the Gitian app on specific repos or orgs — no broad OAuth scopes. Deep links to files and lines. GitLab support coming soon.

Overview

Files842
Stars1.2k
Forks64

Annotations

@gitian:todo12
@gitian:bug3
@gitian:note8
@gitian:deprecated2

Languages

TypeScript68%
CSS18%
JavaScript14%

Repo Dashboard

At-a-glance overview with annotation breakdowns, language stats, recent commits, releases, and documentation — all loading progressively.

How It Works

Three layers, one repo

Capture knowledge in comments. Structure it with docs/ directories. Compose it with directives. All inside your existing git workflow.

my-project/
src/
lib/
auth.ts
utils.ts
components/
Button.tsx
docs/docs
auth.ts.md
README.md
1

Docs Discovery

Gitian scans your repository for docs/ and .docs/ directories to locate documentation. Multiple docs directories at any depth are merged into a single view.

Source

auth.ts

paired

Docs

docs/auth.ts.md

2

Name-based Pairing

Source files are automatically paired with their markdown companion inside docs/ directories by matching filenames.

Docs3
Source

# auth.ts

Handles user authentication via OAuth2. Manages token refresh, session storage, and logout flows.

export function authenticate(provider: string) { ... }
3

Tabbed Result

Files with a documentation companion render a tabbed UI — a Docs tab with the rendered markdown and a Source tab with syntax-highlighted code.

Your code already knows what it does. Gitian helps it say so.

If you've ever written a TODO, a deprecation warning, or a comment explaining why — you've already started. Sign in, install the app on a repo, and see what your code has been saying all along.

Explore demo