kogral/templates/README.md

Knowledge Base Templates

This directory contains Tera templates for generating and exporting knowledge base documents.

Overview

Templates are divided into two categories:

1. Document Templates - Generate new KOGRAL documents with proper frontmatter
2. 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.

Register in config:

{
  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

1. Keep Templates Simple - Focus on structure, not complex logic
2. Use Defaults - Provide sensible defaults with | default(value="...")
3. Indent Consistently - Use | indent(width=2) for nested content
4. Escape User Content - Use | escape for user-provided text in HTML/JSON
5. 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