How to Configure Tolaria for Specific Projects: A Complete Guide to Frontmatter and Type Documents

Tolaria configures projects through convention-over-configuration, storing per-project settings in markdown frontmatter, default templates in type documents, and global policies in settings.json.

Tolaria, the open-source knowledge management tool from refactoringhq/tolaria, treats every project as a markdown note with configurable properties. To configure Tolaria for specific projects, you leverage three distinct scopes: individual note frontmatter for UI customization, type documents for shared defaults, and application settings for vault-wide behaviors. All configuration is stored in plain text files—markdown for notes, JSON for application settings—ensuring full version control compatibility.

Where Configuration Lives

Tolaria implements a hierarchical configuration model that separates concerns between the vault (your notes) and the application.

Per-Note Frontmatter

Individual project configuration lives directly in the markdown file's YAML frontmatter. According to docs/ARCHITECTURE.md line 32, everything that defines how a note is displayed belongs in the note's frontmatter, while app-wide preferences belong elsewhere.

Create a project note by declaring type: Project in the frontmatter:

---
title: "Launch New Website"
type: Project
status: Active
due_date: 2026-09-30
icon: "globe"
_color: "blue"
_width: "wide"
---

# Launch New Website

Project description and tasks...

The type field drives UI chips and sidebar grouping (see docs/ABSTRACTIONS.md lines 18-20). Fields prefixed with an underscore—such as _color and _width—are system properties hidden from the Properties panel and used only by the renderer (ABSTRACTIONS.md lines 32-39).

Per-Type Type Documents

To set defaults for all projects, edit the type document named project.md (created automatically by Tolaria). Type documents use the _isA field to declare which entity type they describe:

---
type: Type
_isA: Project
icon: "rocket"
_color: "purple"
order: 5
sidebar_label: "Projects"
template: |
  ---
  title: "{{title}}"
  type: Project
  status: Active
  ---
  # {{title}}

  ## Goals

  - 

The _isA: Project marker tells Tolaria that this type document describes the Project type (ABSTRACTIONS.md lines 81-89). When you create a new project via src/components/NewNoteDialog.tsx, the UI reads these defaults and serializes them via blocksToMarkdownLossy() (ABSTRACTIONS.md lines 610-618).

Global Application Settings

Installation-local settings affecting all projects reside in ~/.config/com.tolaria.app/settings.json. The Rust backend loads this path via resolve_existing_or_preferred_app_config_path("settings.json") in src-tauri/src/settings.rs lines 220-225. These settings control vault-wide behaviors like auto-archiving completed projects.

Configuring Project Display and Behavior

UI Appearance via System Properties

Control how Tolaria renders your project using system properties in the frontmatter:

• _icon: Sets the sidebar and chip icon (e.g., "rocket", "globe")
• _color: Defines the accent color for the project card
• _width: Controls the editor layout ("wide" or default)

These properties are filtered out by the frontmatter parser in src-tauri/src/frontmatter/yaml.rs before exposing properties to the UI, keeping system concerns separate from user data (ABSTRACTIONS.md lines 34-40).

Runtime Configuration via ProjectSettings.tsx

The Project Settings panel in src/components/ProjectSettings.tsx provides a GUI for editing frontmatter. It uses the useNoteFrontmatter() hook to read values and updateFrontmatterContent() to persist changes. The underlying Rust implementation in src-tauri/src/frontmatter/ops.rs:update_frontmatter_content() (lines 99-104) handles the actual file mutations.

Typical actions include:

• Changing _icon to update the visual identifier
• Toggling _width: "wide" for expanded editor mode
• Adding custom fields like priority: 1
• Creating relationships such as belongs_to: ["[[Q4-2026]]"]

All changes write directly to the markdown file—there is no hidden database.

Implementing Vault-Wide Project Policies

For behaviors that apply to all projects across your vault, configure settings.json:

{
  "autoArchiveCompletedProjects": true,
  "projectDueReminderDays": 7
}

The project-auto-archive hook in src/hooks/useAutoArchive.ts scans for notes with type: Project and status: Done, then processes them according to these global rules. This demonstrates how to configure Tolaria for specific projects while maintaining consistent vault-wide policies.

Programmatic Configuration Examples

Updating System Properties via TypeScript

Interact with Tolaria's Rust backend programmatically using Tauri invocations:

import { invoke } from '@tauri-apps/api/tauri';

async function setProjectWideLayout(notePath: string, wide: boolean) {
  const result = await invoke('update_frontmatter', {
    path: notePath,
    updates: {
      _width: wide ? 'wide' : null, // null removes the key
    },
  });
  return result; // true on success
}

This calls update_frontmatter_content() in src-tauri/src/frontmatter/ops.rs lines 99-104 to mutate the file directly.

Processing Projects in Rust

Create custom hooks that operate on project metadata:

use crate::vault::VaultEntry;

fn auto_archive_completed_projects(vault: &Vault) {
    for entry in vault.entries.iter().filter(|e| e.isA == Some("Project".into())) {
        if let Some(status) = entry.frontmatter.get("status") {
            if status == "Done" && entry.frontmatter.get("due_date").is_some() {
                archive_entry(entry);
            }
        }
    }
}

Summary

• Configure Tolaria for specific projects by setting type: Project in markdown frontmatter and adjusting system properties like _icon, _color, and _width.
• Define defaults for all new projects by editing the project.md type document, which uses _isA: Project to identify itself as the schema for projects.
• Modify settings programmatically using update_frontmatter_content() in src-tauri/src/frontmatter/ops.rs or via the ProjectSettings.tsx UI component.
• Store global policies in ~/.config/com.tolaria.app/settings.json, loaded via resolve_existing_or_preferred_app_config_path().
• Maintain portability because all configuration persists in plain text—markdown for notes, JSON for settings—ensuring Git compatibility and vendor independence.

Frequently Asked Questions

What is the difference between _color and color in Tolaria frontmatter?

_color is a system property that controls the UI accent color for the project card but remains hidden from the Properties panel, while color (without underscore) would appear as a regular custom field in the UI. The underscore prefix signals to the frontmatter parser in src-tauri/src/frontmatter/yaml.rs to filter these keys from the user-facing properties display (ABSTRACTIONS.md lines 34-40).

Where does Tolaria store global application settings?

Tolaria stores global settings in ~/.config/com.tolaria.app/settings.json (or the platform equivalent). The Rust backend resolves this path using resolve_existing_or_preferred_app_config_path("settings.json") in src-tauri/src/settings.rs lines 220-225. These settings affect the entire application instance, unlike frontmatter which controls individual notes.

How do I create a default template for all new projects in Tolaria?

Edit the type document project.md in your vault root and include a template: field in the frontmatter. This field accepts a YAML string that defines the default structure for every new project note. When you create a project via src/components/NewNoteDialog.tsx, Tolaria applies this template via the blocksToMarkdownLossy() pipeline (ABSTRACTIONS.md lines 610-618).

Can I configure Tolaria projects without using the GUI?

Yes. Since Tolaria uses plain markdown files, you can edit project configuration directly with any text editor. Modify the frontmatter in your .md files to change icons, colors, or custom properties, or invoke the Rust commands directly via the Tauri API using invoke('update_frontmatter', ...) as implemented in src-tauri/src/frontmatter/ops.rs lines 99-104.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}