Skip to main content
The project provider handles references between documents within a Colin project. When you write ref('other-doc'), the project provider fetches the compiled output of that document while establishing a dependency edge. This is the foundation of Colin’s dependency system—every internal reference flows through the project provider. The project provider is always registered automatically. No configuration is needed.

​
URI Format

Project URIs use the project:// scheme followed by the document path: 
project://path/to/document.md
In practice, you’ll rarely write full URIs. Colin’s shorthand notation handles the conversion:
ShorthandFull URI
greetingproject://greeting.md
sources/dataproject://sources/data.md
reports/2024/q1project://reports/2024/q1.md
Document paths are relative to your models/ directory. A file at models/context/analysis.md becomes ref('context/analysis').

​
Using ref()

The ref() function fetches a document’s compiled output:
models/product-brief.md
---
name: Product Brief
---

# Company Overview

{{ ref('company').content }}

# Products

{{ ref('products/overview').content }}
When this document compiles, Colin ensures company and products/overview compile first. The .content property contains each document’s full compiled output.

​
Return Value

The ref() function returns a RefResult object with the following properties:
PropertyTypeDescription
contentstrThe compiled document output
namestrDocument name from frontmatter (or filename)
descriptionstr | NoneDescription from frontmatter
uristrThe full project://... URI
updateddatetimeWhen the document was last compiled
templatestrRaw source template before compilation
sourceobject | NoneOriginal domain object (for provider resources)
Access metadata alongside content:
models/index.md
---
name: Document Index
---

{% for doc_uri in ['company', 'products', 'team'] %}
{% set doc = ref(doc_uri) %}
## {{ doc.name }}

{{ doc.description or 'No description available.' }}

{% endfor %}

​
String Conversion

Using a RefResult directly in a string context returns a placeholder, not the content: 
{{ ref('company') }}
Outputs: Ref('project://company.md') Always use .content to get the actual content: 
{{ ref('company').content }}

​
Dependency Tracking

Every ref() call creates a dependency edge in Colin’s compilation graph. These edges determine:
  1. Compilation order - Referenced documents compile before their dependents
  2. Change propagation - When a document changes, dependents recompile
  3. Lineage tracking - The manifest records the full dependency graph
Consider this document structure: 
company.md
    ↓
product-brief.md (refs company)
    ↓
sales-deck.md (refs product-brief)
If company.md changes, Colin recompiles all three. If only sales-deck.md changes, only it recompiles. Dependencies appear in the manifest: 
{
  "documents": {
    "project://product-brief.md": {
      "refs_evaluated": ["project://company.md"]
    },
    "project://sales-deck.md": {
      "refs_evaluated": ["project://product-brief.md"]
    }
  }
}

​
Combining with Filters

Transform referenced content using filters:
models/summary.md
---
name: Executive Summary
---

{{ ref('full-report') | llm_extract('the 3 most important findings') }}
The extract() filter passes the RefResult through an LLM with your prompt. Since RefResult carries metadata, the LLM sees the document name and description alongside its content. Build complex analyses by combining multiple refs:
models/comparison.md
---
name: Quarterly Comparison
---

{% llm %}
Compare these two reports and identify trends:

Q1: {{ ref('reports/q1').content }}
Q2: {{ ref('reports/q2').content }}

Focus on revenue changes and customer growth.
{% endllm %}

​
Compiled Outputs

References point to compiled outputs, not source files. When you reference a document:
  1. Colin compiles the source document (if needed)
  2. The compiled output is stored in output/
  3. ref() reads from the compiled output
This means a reference to ref('data') returns the result of compiling models/data.md, including any template expansions, LLM calls, and nested references that document performed.

​
Path Resolution

Document paths strip the models/ prefix. Given this project structure: 
models/
  company.md
  products/
    main.md
    enterprise.md
  context/
    market-analysis.md
References use paths relative to models/: 
{{ ref('company').content }}
{{ ref('products/main').content }}
{{ ref('context/market-analysis').content }}
Colin validates references at compile time. A reference to a document that hasn’t been compiled yet fails with a clear error: 
RefNotCompiledError: ref('missing.md') failed - document not compiled.
Add 'depends_on: [missing.md]' to ensure compilation order,
or use ref('missing.md', allow_stale=True) to accept stale/missing data.