# How to Use Tolaria for Code Transformation: Markdown Processing Utilities Explained

> Discover how to use Tolaria for code transformation. This guide explains its TypeScript utilities for converting markdown with wikilinks and LaTeX to BlockNote data and back for programmatic manipulation.

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

---

**Tolaria exposes pure TypeScript utility functions that convert raw markdown—complete with wikilinks and LaTeX math—into BlockNote data structures and back again, enabling programmatic manipulation of note content without UI dependencies.**

The open-source note-taking application [refactoringhq/tolaria](https://github.com/refactoringhq/tolaria) provides a robust transformation layer for processing markdown content. Understanding how to use Tolaria for code transformation allows developers to programmatically parse, modify, and generate notes using stateless functions found in the `src/utils/` directory.

## Architecture of Tolaria Code Transformation

Tolaria's transformation pipeline consists of discrete, composable utilities that handle specific markdown constructs. These functions are stateless and fully typed, making them safe to use in scripts, tests, or external integrations.

### Wikilink Preprocessing and Expansion

The wikilink system uses a two-phase approach to preserve link integrity through BlockNote's parser. In [[`src/utils/wikilinks.ts`](https://github.com/refactoringhq/tolaria/blob/main/src/utils/wikilinks.ts)](https://github.com/refactoringhq/tolaria/blob/main/src/utils/wikilinks.ts), the `preProcessWikilinks` function scans raw markdown and replaces `[[Note Title]]` syntax with placeholder tokens that survive round-trip parsing. After BlockNote generates the block tree, `injectWikilinks` (which internally calls `expandWikilinksInContent`) restores these placeholders to proper `wikilink` inline items.

### Math Markdown Detection

For mathematical notation, Tolaria provides [[`src/utils/mathMarkdown.ts`](https://github.com/refactoringhq/tolaria/blob/main/src/utils/mathMarkdown.ts)](https://github.com/refactoringhq/tolaria/blob/main/src/utils/mathMarkdown.ts), which contains `transformBlockContent` to detect inline LaTeX (`$...$`) and block math (`$$...$$`). This utility converts detected math into specially-typed inline items that the editor renders, while preserving the original markdown syntax for export.

### Block Tree Traversal

The generic `walkBlocks` function in [[`wikilinks.ts`](https://github.com/refactoringhq/tolaria/blob/main/wikilinks.ts)](https://github.com/refactoringhq/tolaria/blob/main/src/utils/wikilinks.ts) recursively traverses the BlockNote tree, applying a supplied transformation to every block's inline content. This serves as the engine for all content-level transformations, including wikilink expansion and math processing.

### Snippet and Metadata Extraction

Beyond structural conversion, Tolaria includes utilities for content analysis. The `extractSnippet` function generates plain-text previews by stripping front-matter, headings, and markdown syntax, while `countWords` provides accurate word counts ignoring markup and wikilinks. Both reside in [[`src/utils/wikilinks.ts`](https://github.com/refactoringhq/tolaria/blob/main/src/utils/wikilinks.ts)](https://github.com/refactoringhq/tolaria/blob/main/src/utils/wikilinks.ts).

## Converting Markdown to BlockNote Structures

To transform raw markdown containing wikilinks and math into Tolaria's internal block representation, chain the preprocessing, parsing, and injection utilities:

```typescript
import { preProcessWikilinks, injectWikilinks } from '@/utils/wikilinks';
import { parseMarkdownToBlocks } from '@/utils/markdownParser';

// Raw markdown with special syntax
const rawMarkdown = `

# Quantum Notes

See [[Relativity]] for context. Energy equals $E = mc^2$.
`;

// 1. Replace wikilinks with placeholders
const preProcessed = preProcessWikilinks(rawMarkdown);

// 2. Parse to BlockNote blocks
const blockTree = parseMarkdownToBlocks(preProcessed);

// 3. Expand placeholders to proper wikilink items
const enrichedBlocks = injectWikilinks(blockTree);

```

This three-step pipeline ensures that both wikilinks and mathematical expressions survive the parsing process and remain editable within Tolaria's block-based editor.

## Exporting BlockNote Back to Markdown

When persisting changes or exporting notes, reverse the transformation to restore markdown syntax:

```typescript
import { restoreWikilinksInBlocks } from '@/utils/wikilinks';
import { blocksToMarkdown } from '@/utils/markdownRenderer';

// Assuming `editedBlocks` is your current BlockNote tree
const cleanedBlocks = restoreWikilinksInBlocks(editedBlocks);
const markdownOutput = blocksToMarkdown(cleanedBlocks);

```

The `restoreWikilinksInBlocks` function (which internally uses `collapseWikilinksInContent`) converts wikilink inline items back to `[[Note Title]]` syntax, ensuring the exported markdown remains compatible with standard editors.

## Utility Transformations for Content Analysis

### Extracting Search Snippets

For generating search result previews or backlink summaries, use the `extractSnippet` function:

```typescript
import { extractSnippet } from '@/utils/wikilinks';

const noteContent = await fetchNoteContent('note-id');
const snippet = extractSnippet(noteContent);
// Returns: "See Relativity for context. Energy equals E = mc^2..."

```

This utility removes YAML front-matter, heading markers, and list syntax while preserving approximately 160 characters of readable text.

### Counting Words Without Markup

To calculate document length excluding markdown syntax:

```typescript
import { countWords } from '@/utils/wikilinks';

const totalWords = countWords(noteContent);
console.log(`Document contains ${totalWords} words`);

```

The `countWords` function ignores front-matter blocks, wikilink brackets, and punctuation, providing accurate metrics for reading time calculations.

## Key Source Files and Functions

The following files constitute Tolaria's transformation layer:

- **[[`src/utils/wikilinks.ts`](https://github.com/refactoringhq/tolaria/blob/main/src/utils/wikilinks.ts)](https://github.com/refactoringhq/tolaria/blob/main/src/utils/wikilinks.ts)** – Core transformation logic including `preProcessWikilinks`, `injectWikilinks`, `restoreWikilinksInBlocks`, `extractSnippet`, `countWords`, `splitFrontmatter`, and `walkBlocks`
- **[[`src/utils/mathMarkdown.ts`](https://github.com/refactoringhq/tolaria/blob/main/src/utils/mathMarkdown.ts)](https://github.com/refactoringhq/tolaria/blob/main/src/utils/mathMarkdown.ts)** – Math-specific processing with `transformBlockContent` and related helpers
- **[[`src/utils/windowMode.ts`](https://github.com/refactoringhq/tolaria/blob/main/src/utils/windowMode.ts)](https://github.com/refactoringhq/tolaria/blob/main/src/utils/windowMode.ts)** – UI state utilities (often paired with transformations)
- **[[`src/components/MarkdownContent.test.tsx`](https://github.com/refactoringhq/tolaria/blob/main/src/components/MarkdownContent.test.tsx)](https://github.com/refactoringhq/tolaria/blob/main/src/components/MarkdownContent.test.tsx)** – Test suite demonstrating transformation pipelines
- **[[`src/components/RawEditorFindBar.tsx`](https://github.com/refactoringhq/tolaria/blob/main/src/components/RawEditorFindBar.tsx)](https://github.com/refactoringhq/tolaria/blob/main/src/components/RawEditorFindBar.tsx)** – UI component consuming transformed blocks for find-replace operations

## Summary

- **Tolaria** provides stateless TypeScript utilities in [`src/utils/wikilinks.ts`](https://github.com/refactoringhq/tolaria/blob/main/src/utils/wikilinks.ts) and [`src/utils/mathMarkdown.ts`](https://github.com/refactoringhq/tolaria/blob/main/src/utils/mathMarkdown.ts) for bidirectional markdown transformation.
- The **two-phase wikilink pipeline** (`preProcessWikilinks` → parse → `injectWikilinks`) preserves link integrity through BlockNote's parser.
- **Math markdown** processing converts LaTeX syntax to structured inline items while maintaining export compatibility.
- **Content analysis** functions like `extractSnippet` and `countWords` operate on raw markdown to generate metadata without UI dependencies.
- All utilities are pure functions that can be imported into external scripts, tests, or custom tooling for batch processing or migration tasks.

## Frequently Asked Questions

### What is the primary utility for handling wikilinks in Tolaria?

The primary wikilink logic resides in [[`src/utils/wikilinks.ts`](https://github.com/refactoringhq/tolaria/blob/main/src/utils/wikilinks.ts)](https://github.com/refactoringhq/tolaria/blob/main/src/utils/wikilinks.ts), which exports `preProcessWikilinks` for tokenizing links before parsing and `injectWikilinks` (which internally calls `expandWikilinksInContent`) for converting tokens back to structured wikilink items after BlockNote generates the block tree.

### How does Tolaria handle LaTeX math during transformation?

Tolaria detects inline (`$...$`) and block (`$$...$$`) math through utilities in [[`src/utils/mathMarkdown.ts`](https://github.com/refactoringhq/tolaria/blob/main/src/utils/mathMarkdown.ts)](https://github.com/refactoringhq/tolaria/blob/main/src/utils/mathMarkdown.ts). The `transformBlockContent` function replaces math expressions with typed inline items that render properly in the editor, while preserving the original markdown for round-trip export.

### Can I use Tolaria transformation utilities outside the React UI?

Yes. All transformation functions in [`src/utils/wikilinks.ts`](https://github.com/refactoringhq/tolaria/blob/main/src/utils/wikilinks.ts) and [`src/utils/mathMarkdown.ts`](https://github.com/refactoringhq/tolaria/blob/main/src/utils/mathMarkdown.ts) are pure TypeScript functions with no React dependencies. You can import them into Node.js scripts, CLI tools, or automated migration pipelines to process Tolaria notes without launching the full application interface.

### Which function extracts plain text previews from markdown notes?

The `extractSnippet` function in [[`src/utils/wikilinks.ts`](https://github.com/refactoringhq/tolaria/blob/main/src/utils/wikilinks.ts)](https://github.com/refactoringhq/tolaria/blob/main/src/utils/wikilinks.ts) removes front-matter, headings, and markdown syntax to generate approximately 160 characters of clean text, suitable for search result previews and backlink summaries.