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

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 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), 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), 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/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).

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:

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:

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:

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:

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) – 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) – Math-specific processing with transformBlockContent and related helpers
• [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) – Test suite demonstrating transformation pipelines
• [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 and 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), 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). 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 and 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) removes front-matter, headings, and markdown syntax to generate approximately 160 characters of clean text, suitable for search result previews and backlink summaries.

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