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

> Configure Tolaria for specific projects using frontmatter and type documents. This guide details how to customize settings for your projects with Tolaria.

- Repository: [Refactoring/tolaria](https://github.com/refactoringhq/tolaria)
- Tags: how-to-guide
- Published: 2026-05-04

---

**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`](https://github.com/refactoringhq/tolaria/blob/main/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`](https://github.com/refactoringhq/tolaria/blob/main/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:

```markdown
---
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`](https://github.com/refactoringhq/tolaria/blob/main/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`](https://github.com/refactoringhq/tolaria/blob/main/project.md) (created automatically by Tolaria). Type documents use the `_isA` field to declare which entity type they describe:

```markdown
---
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`](https://github.com/refactoringhq/tolaria/blob/main/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`](https://github.com/refactoringhq/tolaria/blob/main/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`](https://github.com/refactoringhq/tolaria/blob/main/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`](https://github.com/refactoringhq/tolaria/blob/main/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`](https://github.com/refactoringhq/tolaria/blob/main/settings.json):

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

```

The **project-auto-archive hook** in [`src/hooks/useAutoArchive.ts`](https://github.com/refactoringhq/tolaria/blob/main/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:

```typescript
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`](https://github.com/refactoringhq/tolaria/blob/main/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:

```rust
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`](https://github.com/refactoringhq/tolaria/blob/main/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`](https://github.com/refactoringhq/tolaria/blob/main/src-tauri/src/frontmatter/ops.rs) or via the [`ProjectSettings.tsx`](https://github.com/refactoringhq/tolaria/blob/main/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`](https://github.com/refactoringhq/tolaria/blob/main/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`](https://github.com/refactoringhq/tolaria/blob/main/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`](https://github.com/refactoringhq/tolaria/blob/main/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`](https://github.com/refactoringhq/tolaria/blob/main/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`](https://github.com/refactoringhq/tolaria/blob/main/src-tauri/src/frontmatter/ops.rs) lines 99-104.