Documentation

Wikilinks

Navigate between documents using Obsidian's [[wikilink]] syntax. Links are resolved across the entire vault hierarchy using shortest-path matching, just like Obsidian.

[[Page]]                   → link to Page.md
[[Page|Display Text]]      → custom display text
[[Page#Heading]]           → anchor to a heading
[[folder/Page]]            → nested path
[[Page#Heading|Click me]]  → all combined

• -Resolved links render as clickable navigation within the vault
• -Unresolved links render with strikethrough styling
• -Resolution order: exact match → with .md → with .mdx → relative path → shortest path across vault → fallback to other vaults

Callouts

All Obsidian callout types are supported with proper icons, colors, and nesting.

> [!note] Title here
> Callout body text. Supports **markdown** inside.

> [!warning]+ Expanded by default
> Use + for expanded, - for collapsed.

> [!tip]- Collapsed by default
> Click to expand.

Mermaid Diagrams

Flowcharts, sequence diagrams, ERDs, and all other Mermaid diagram types render inline. Powered by Mermaid 11 with DOMPurify sanitization.

```mermaid
graph TD
    A[Write docs] --> B[Push to GitHub]
    B --> C[Browse in Gitian]
```

KaTeX Math

Inline and display math expressions render via KaTeX with full LaTeX support.

The equation $E = mc^2$ is well known.

$$
\frac{-b \pm \sqrt{b^2 - 4ac}}{2a}
$$

Code Highlighting

Fenced code blocks are syntax-highlighted using highlight.js with support for 100+ languages. Line numbers are included automatically.

```typescript
export function greet(name: string) {
  return `Hello, ${name}!`;
}
```

Frontmatter

YAML frontmatter at the top of markdown files is parsed and displayed as a banner above the content. Array values render as badge pills.

---
title: Authentication Module
tags: [auth, security, session]
status: stable
---

# Authentication

Content starts here...

GitHub Flavored Markdown

Full GFM support via remark-gfm, including tables, strikethrough, autolinks, and task lists.

| Feature    | Status |
|------------|--------|
| Wikilinks  | ✓      |
| Callouts   | ✓      |

~~strikethrough~~ and https://auto.link

- [x] Completed task
- [ ] Pending task

Vault Discovery

Gitian scans your repo for .obsidian/ directories to locate documentation vaults. Multiple vaults at different depths are supported with parent-child scoping.

my-project/
├── .obsidian/          ← root vault (covers entire repo)
│   ├── README.md.md
│   └── config.ts.md
├── src/
│   ├── .obsidian/      ← nested vault (scoped to src/)
│   │   └── auth.ts.md
│   ├── auth.ts
│   └── utils.ts
└── README.md

• -Each .obsidian/ directory defines a vault
• -Nested vaults override the parent within their subtree
• -Files are assigned to the deepest vault that contains them
• -The .obsidian/ directory itself is an Obsidian vault — open it in Obsidian desktop for graph view, backlinks, and plugins

File-Doc Pairing

Source files are automatically paired with markdown companions inside the nearest .obsidian/ directory by matching filenames.

Source file          → Doc file
auth.ts              → .obsidian/auth.ts.md
Button.tsx           → .obsidian/Button.tsx.md
examples/            → .obsidian/examples.md (directory doc)

• -Paired files show a tabbed UI — Docs tab with rendered markdown and Source tab with syntax-highlighted code
• -Directory-level docs use the directory name (e.g. examples.md for the examples/ folder)
• -Docs support all Obsidian features: wikilinks, callouts, math, diagrams, etc.

@gitian Annotations

Generates IDE-style documentation blocks. The parser captures the description and the full function body following the comment.

// @gitian Validates user input before processing.
// Throws on invalid email format.
export function validateUser(input: UserInput) {
  // ... function body is captured automatically
}

/* @gitian
 * Session manager — handles encrypted cookie storage
 * and token refresh for authenticated GitHub sessions.
 */
export class SessionManager {
  // ... class body is captured automatically
}

# @gitian Request rate limiter using token bucket algorithm
def rate_limit(request):
    # ... function body is captured by indentation

• -Contiguous comment lines after the tag become the description (rendered as markdown)
• -The code block following the comment is captured using brace-depth tracking (or indentation for Python/YAML)
• -Rendered in the Docs tab with syntax-highlighted code and line numbers

@todo Tags

Marks a work item inline. Todos are collected and displayed in a collapsible list above annotations — no code is captured.

// @todo Add rate limiting per IP address

/* @todo Refactor to use the new cache helper */

{/* @todo Add input validation and character count */}

• -The text after @todo becomes the description
• -No code block is captured — todos are lightweight markers
• -Rendered as a collapsible amber-colored list in the Docs tab, collapsed by default
• -A separate todo count badge appears in the tab header

Supported Comment Styles

Both @gitian and @todo work with all of these comment styles.