lat.md

The lat.md format uses Obsidian-style wiki links [[target]] or [[target|alias]] to create connections between markdown sections and source code symbols.

Markdown Section Links

Targets are hierarchical paths starting from the vault root (the project directory). All paths must include the lat.md/ prefix.

Resolution Rules:

• [[foo]]: Links to the root section of foo.md.
• [[foo#Bar]]: Links to heading Bar in foo.md. The path after # must be an exact heading chain (e.g., [[file#Heading1#Heading2]]).
• [[path/foo#Bar]]: Fully qualified link to path/foo.md at heading Bar.

Source Code Links

You can link directly to symbols in supported languages (.ts, .tsx, .js, .jsx, .py, .rs, .go, .c, .h).

• TypeScript/JavaScript: [[src/config.ts#getConfigDir]] (function) or [[src/server.ts#App#listen]] (method on class).
• Python: [[file.py#my_func]] (functions, classes, methods, or module-level variables). Decorators are unwrapped automatically.
• Rust: [[file.rs#Type#method]] (functions, structs, enums, traits, impl methods, consts, statics, type aliases).
• Go: [[file.go#Type#Method]] (functions, types, methods with receivers, consts, vars).
• C: [[file.h#Struct#field]] (functions, structs, fields, enums, typedefs, #define macros, variables).

Note: Source code references always require the full path; short path disambiguation does not apply to source files.

[[lat.md/guides/setup#Install]]
[[src/config.ts#getConfigDir]]
[[src/server.ts#App#listen]]
[[src/lib.rs#Greeter#greet]]

The project uses a structured knowledge graph in lat.md/ using specific syntax for cross-referencing:

Section IDs

• Full form: lat.md/path/to/file#Heading#SubHeading (e.g., lat.md/tests/search#RAG Replay Tests).
• Short form: Uses the bare filename if unique (e.g., search#RAG Replay Tests).

Wiki Links

Use [[target]] or [[target|alias]] to link between markdown sections. You can also link directly to source code:

• TypeScript/JavaScript: [[src/foo.ts#myFunction]] or [[src/server.ts#App#listen]] for class methods.
• Python: [[lib/utils.py#parse_args]].
• Rust: [[src/lib.rs#Greeter#greet]].
• Go: [[src/app.go#Greeter#Greet]].
• C: [[src/app.h#Greeter]] for structs.

Code References (Tying Code to Docs)

To link source code to a specific documentation section, use a comment next to the relevant code block:

• JS/TS/Rust/Go/C: // @lat: [[section-id]]
• Python: # @lat: [[section-id]]

The embedding backend used by lat search is determined by the index metadata. If no index exists, the backend is decided based on the presence of an API key.

Key Resolution Priority:

1. LAT_LLM_KEY (Environment Variable)
2. LAT_LLM_KEY_FILE (Environment Variable)
3. LAT_LLM_KEY_HELPER (Environment Variable)
4. llm_key (Config file)

Provider Detection based on Key Prefix:

• No key: Uses local @lat.md/embed-minilm-fp16 (all-MiniLM-L6-v2, 384 dims).
• sk-...: Uses OpenAI (text-embedding-3-small, 1536 dims).
• vck_...: Uses Vercel AI Gateway (openai/text-embedding-3-small, 1536 dims).
• sk-ant-...: Anthropic (not supported; will result in an error).

Note: If you change your provider or key, you must run lat reindex to rebuild the index with the correct dimensions. The system will not silently switch models as vectors from different models are incompatible.

The lat.md system creates a knowledge graph for your codebase by using a lat.md/ directory at your project root. This graph connects high-level documentation to your actual source code using specific linking syntaxes.

Linking Patterns

• Wiki Links: Link between markdown sections using [[file#Section#Subsection]] syntax.
• Code Links: Link markdown files directly to source code symbols using [[path/to/file.ext#symbol]] (e.g., [[src/auth.ts#validateToken]]).
• Code Annotations: Tie implementation back to documentation by adding comments in your source files:
  • TypeScript/JavaScript: // @lat: [[section-id]]
  • Python: # @lat: [[section-id]]

Example Structure

my-project/
├── lat.md/
│   ├── architecture.md    # system design, key decisions
│   ├── auth.md            # authentication & authorization logic
│   └── tests.md           # test specs (require-code-mention: true)
├── src/
│   ├── auth.ts            # // @lat: [[auth#OAuth Flow]]
│   └── server.ts          # // @lat: [[architecture#Request Pipeline]]
└── ...

my-project/
├── lat.md/
│   ├── architecture.md    # system design, key decisions
│   ├── auth.md            # authentication & authentication logic
│   └── tests.md           # test specs (require-code-mention: true)
├── src/
│   ├── auth.ts            # // @lat: [[auth#OAuth Flow]]
│   └── server.ts          # // @lat: [[architecture#Request Pipeline]]
└── ...