Symbol Transclusion
Embed live code into your documentation by name, not line number. Edit the source, your docs update automatically.
# Embed a function by name
![[auth.py#validate_token]]Ohai extracts the validate_token function from auth.py and renders it inline with syntax highlighting. When the function changes, your docs update automatically.
Why it matters
Traditional documentation rots. You copy-paste code into markdown, the code evolves, and suddenly your docs are lying to you. Symbol transclusion fixes this by treating your source files as the single source of truth.
Unlike line-number references that break with every refactor, symbol transclusion uses AST parsing to find code by its actual name—functions, classes, structs, constants. Rename a file, reorganize your code, add new methods—as long as the symbol name exists, your docs stay accurate.
Use Cases
API Documentation
Reference your actual function signatures, not hand-typed approximations that drift out of sync.
Architecture Decision Records
Embed the code you're discussing in ADRs. The examples stay current as the codebase evolves.
Onboarding Guides
Show new developers how authentication works with live code they can trust matches the repo.
Code Reviews
Pull specific functions into a markdown summary for async review and discussion.
Tutorials
Walk through real implementations. Readers can trust the code examples are always up to date.
Runbooks
Embed the exact config or script that ops needs to reference during incidents.
Supported Languages
30+ languages via Tree-sitter AST parsing. Even JSON keys, YAML paths, and TOML tables.
Ready to try documentation that never goes stale?
Download for Mac