Document Templates - Generate new KOGRAL documents with proper frontmatter
Export Templates - Export KOGRAL data to various formats (Logseq, JSON, reports)

Document Templates

Located in the root templates/ directory. Used to create new knowledge base entries.

Available Templates

Template	Purpose	Node Type
`note.md.tera`	General notes and observations	note
`decision.md.tera`	Architectural Decision Records (ADR)	decision
`guideline.md.tera`	Code guidelines and best practices	guideline
`pattern.md.tera`	Design patterns and solutions	pattern
`journal.md.tera`	Daily notes and journal entries	journal
`execution.md.tera`	Agent execution records (from Vapora)	execution

Template Variables

All document templates receive these common variables:

{
  id: String,              // UUID
  title: String,           // Node title
  created: DateTime,       // ISO 8601 timestamp
  modified: DateTime,      // ISO 8601 timestamp
  tags: Vec<String>,       // Tags
  status: NodeStatus,      // draft, active, superseded, archived
  content: String,         // Markdown content
  relates_to: Vec<String>, // Related node IDs
  depends_on: Vec<String>, // Dependency node IDs
  implements: Vec<String>, // Pattern/guideline node IDs
  extends: Vec<String>,    // Extension node IDs
  project: Option<String>, // Project identifier
}

Type-Specific Variables

Decision (ADR):

{
  context: String,           // Problem context
  decision: String,          // Decision made
  consequences: Vec<String>, // Impacts
  alternatives: Vec<{        // Alternatives considered
    name: String,
    description: String,
    pros: Vec<String>,
    cons: Vec<String>,
  }>,
}

Guideline:

{
  language: String,     // Programming language
  category: String,     // Category (error-handling, testing, etc.)
  overview: String,     // Brief overview
  rules: Vec<{          // Guideline rules
    title: String,
    description: String,
    rationale: String,
  }>,
  examples: Vec<{       // Code examples
    title: String,
    good: String,       // Good practice
    bad: String,        // Bad practice
    explanation: String,
  }>,
  exceptions: Vec<String>,
}

Pattern:

{
  problem: String,           // Problem statement
  solution: String,          // Solution description
  forces: Vec<String>,       // Constraints/forces
  context: String,           // When to use
  structure: String,         // Pattern structure
  implementation: Vec<{      // Implementation steps
    title: String,
    description: String,
    code: String,
    language: String,
  }>,
  consequences: {
    benefits: Vec<String>,
    drawbacks: Vec<String>,
  },
}

Journal:

{
  date: String,             // Date (YYYY-MM-DD)
  tasks: Vec<{              // Tasks for the day
    description: String,
    completed: bool,
  }>,
  highlights: Vec<String>,  // Daily highlights
  learnings: Vec<String>,   // Things learned
  links: Vec<String>,       // Related node IDs
}

Execution:

{
  task_type: String,        // Type of task
  agent: String,            // Agent name
  outcome: String,          // success, failure, etc.
  duration_ms: u64,         // Execution time
  steps: Vec<{              // Execution steps
    description: String,
    duration_ms: u64,
    result: String,
  }>,
  errors: Vec<{             // Errors encountered
    type: String,
    message: String,
    details: String,
  }>,
  metrics: Vec<{            // Performance metrics
    name: String,
    value: f64,
    unit: String,
  }>,
}

Export Templates

Located in templates/export/. Used to export KOGRAL data to external formats.

Available Export Templates

Template	Format	Purpose
`logseq-page.md.tera`	Logseq Markdown	Export single node to Logseq page
`logseq-journal.md.tera`	Logseq Markdown	Export journal to Logseq daily note
`summary.md.tera`	Markdown Report	Generate KOGRAL summary report
`graph.json.tera`	JSON	Export entire graph to JSON

Export Template Variables

Logseq Export:

{
  node: Node,  // Full node object
}

Summary Export:

{
  graph: {
    name: String,
    version: String,
    description: String,
  },
  timestamp: DateTime,
  stats: {
    total_nodes: usize,
    total_edges: usize,
    nodes_by_type: HashMap<NodeType, usize>,
    nodes_by_status: HashMap<NodeStatus, usize>,
    top_tags: Vec<(String, usize)>,
  },
  nodes: Vec<Node>,
}

JSON Export:

{
  graph: Graph,
  nodes: Vec<Node>,
  edges: Vec<Edge>,
  stats: Statistics,
}

Usage Examples

Generate a New Note

use kb_core::export::tera::TeraEngine;
use kb_core::models::{Node, NodeType};

let tera = TeraEngine::new(Path::new("templates"))?;
let mut node = Node::new(NodeType::Note, "My Note".to_string());
node.content = "This is my note content".to_string();
node.tags = vec!["rust".to_string(), "kogral".to_string()];

let markdown = tera.render_node(&node)?;

Export to Logseq

let logseq_md = tera.export_logseq(&node)?;
std::fs::write(".logseq/pages/my-note.md", logseq_md)?;

Generate Summary Report

use tera::Context;

let mut context = Context::new();
context.insert("graph", &graph);
context.insert("timestamp", &Utc::now());
context.insert("stats", &statistics);
context.insert("nodes", &nodes);

let summary = tera.render_custom("export/summary.md.tera", &context)?;

Customization

Override Default Templates

Copy a template and modify it:

cp templates/note.md.tera my-templates/custom-note.md.tera
# Edit my-templates/custom-note.md.tera

Update configuration:

{
  templates = {
    templates_dir = "my-templates",
    templates = {
      note = "custom-note.md.tera",
    },
  },
}

Create Custom Templates

Add to templates/custom/:

---
id: {{ id }}
title: {{ title }}
custom_field: {{ my_custom_field }}
---

# {{ title }}

Custom template content here.

{
  templates = {
    custom = {
      my-template = "custom/my-template.md.tera",
    },
  },
}

Template Syntax

Templates use Tera syntax (similar to Jinja2):

Variables

{{ variable }}
{{ object.field }}
{{ array.0 }}

Filters

{{ text | upper }}
{{ date | date(format="%Y-%m-%d") }}
{{ content | truncate(length=100) }}
{{ json_data | json_encode | safe }}

Conditionals

{% if condition %}
  ...
{% elif other_condition %}
  ...
{% else %}
  ...
{% endif %}

Loops

{% for item in items %}
  {{ item }}
{% endfor %}

{% for key, value in map %}
  {{ key }}: {{ value }}
{% endfor %}

Comments

{# This is a comment #}

YAML Frontmatter

All document templates generate YAML frontmatter compatible with:

Logseq - Wikilinks, properties
kogral-core parser - Full schema validation
Git - Human-readable diffs

Example:

---
id: abc-123
type: note
title: My Note
created: 2026-01-17T10:30:00Z
modified: 2026-01-17T10:30:00Z
tags: ["rust", "kogral"]
status: draft
relates_to:
  - other-note-id
---

Best Practices

Keep Templates Simple - Focus on structure, not complex logic
Use Defaults - Provide sensible defaults with | default(value="...")
Indent Consistently - Use | indent(width=2) for nested content
Escape User Content - Use | escape for user-provided text in HTML/JSON
Document Custom Fields - Add comments explaining custom template variables

Troubleshooting

Template Not Found

Ensure templates_dir in config points to the correct directory:

templates = {
  templates_dir = "templates",  // Relative to project root
}

Variable Not Found

Check that the variable is provided in the template context. Add a default:

{{ variable | default(value="") }}

Rendering Errors

Enable debug mode to see detailed error messages:

let tera = Tera::new("templates/**/*.tera")?;
tera.autoescape_on(vec![]); // Disable autoescaping for markdown

References

Tera Documentation
Logseq Markdown Format
kogral-core models: crates/kogral-core/src/models.rs
Template engine: crates/kogral-core/src/export/tera.rs