Obsidian Markdown Parsing

Relevant source files

• src/vault-mcp/obsidian-markdown/__tests__/callouts.test.ts
• src/vault-mcp/obsidian-markdown/__tests__/headings.test.ts
• src/vault-mcp/obsidian-markdown/__tests__/lines.test.ts
• src/vault-mcp/obsidian-markdown/__tests__/links.test.ts
• src/vault-mcp/obsidian-markdown/__tests__/memory-entries.test.ts
• src/vault-mcp/obsidian-markdown/__tests__/plaintext.test.ts
• src/vault-mcp/obsidian-markdown/__tests__/tasks.test.ts
• src/vault-mcp/obsidian-markdown/callouts.ts
• src/vault-mcp/obsidian-markdown/canvas.ts
• src/vault-mcp/obsidian-markdown/frontmatter.ts
• src/vault-mcp/obsidian-markdown/headings.ts
• src/vault-mcp/obsidian-markdown/lines.ts
• src/vault-mcp/obsidian-markdown/links.ts
• src/vault-mcp/obsidian-markdown/memory-entries.ts
• src/vault-mcp/obsidian-markdown/plaintext.ts
• src/vault-mcp/obsidian-markdown/tasks.ts
• src/vault-mcp/search/__tests__/task-queries.test.ts
• src/vault-mcp/vault-operations/__tests__/note-mover.test.ts
• src/vault-mcp/vault-operations/note-mover.ts

The obsidian-markdown/ layer is a pure functional domain for parsing and transforming Obsidian-flavored Markdown. It is architecturally significant because it encodes Obsidian-parity behavior—such as complex link resolution, task metadata extraction, and code-fence awareness—without performing any filesystem I/O or SQLite queries src/vault-mcp/obsidian-markdown/links.ts1-5

By isolating this logic, Vault Cortex ensures that the indexer, the note-patcher, and the link-rewriter all share a single source of truth regarding the structure of a note src/vault-mcp/obsidian-markdown/links.ts3-5

Link Engine (links.ts)

The link engine handles the grammar, extraction, and resolution of all Obsidian link formats. It is designed to be "fence-aware," meaning it can ignore links inside backticks or code blocks during extraction src/vault-mcp/obsidian-markdown/links.ts1-11

Supported Link Formats

The parser recognizes three primary categories of links:

1. Wikilinks: [[target]], [[target|alias]], [[target#heading]], and embeds ![[target]] src/vault-mcp/obsidian-markdown/links.ts18-21 It includes specialized handling for Obsidian's table-pipe escaping (\|) where a trailing backslash on a target is stripped and shifted into the alias src/vault-mcp/obsidian-markdown/links.ts151-160
2. Markdown Links: <FileRef file-url="https://github.com/aliasunder/vault-cortex/blob/c69495e3/text" undefined file-path="text">Hii</FileRef> or <FileRef file-url="https://github.com/aliasunder/vault-cortex/blob/c69495e3/text" undefined file-path="text">Hii</FileRef>. It specifically filters for .md extensions and excludes external URLs via a URI-scheme lookahead src/vault-mcp/obsidian-markdown/links.ts32-33 src/vault-mcp/obsidian-markdown/links.ts50-55
3. Frontmatter Links: Links embedded within YAML properties (e.g., related: [[Note]]), extracted via specialized logic that understands property-block syntax src/vault-mcp/obsidian-markdown/links.ts181-185

Link Resolution Logic

Resolution follows Obsidian's "New link format" modes, handled by resolveTargetToPath src/vault-mcp/obsidian-markdown/links.ts205-207:

• Relative Path: Paths starting with ./ or ../ relative to the sourcePath src/vault-mcp/obsidian-markdown/links.ts221-224
• Absolute Path: Paths relative to the vault root src/vault-mcp/obsidian-markdown/links.ts226-228
• Shortest Path: Resolving a bare filename to its full vault path using a provided allPaths lookup src/vault-mcp/obsidian-markdown/links.ts230-235

Diagram: Link Extraction Pipeline

Sources: src/vault-mcp/obsidian-markdown/links.ts117-130 src/vault-mcp/obsidian-markdown/lines.ts16-20 src/vault-mcp/obsidian-markdown/links.ts165-170

Line and Fence Management (lines.ts)

This module provides the low-level primitives for splitting content and tracking state. It implements the CommonMark §4.5 fenced-code state machine and Obsidian %% %% comment state machine src/vault-mcp/obsidian-markdown/lines.ts5-7

• splitIntoLines: Normalizes line endings by stripping trailing \r (CR), ensuring consistent behavior for CRLF (Windows) files across the entire parser layer src/vault-mcp/obsidian-markdown/lines.ts16-20
• advanceFence: Tracks backtick (`) or tilde (~) fences. It is blockquote-aware, recognizing fences inside callouts (e.g., > ``` ) and handling implicit closure when a blockquote container ends src/vault-mcp/obsidian-markdown/lines.ts101-118
• advanceComment: Toggles comment state based on %% delimiters at line boundaries. It distinguishes between mid-line text (like 100%%) and actual comment markers src/vault-mcp/obsidian-markdown/lines.ts158-172
• classifyLines: A higher-level utility that runs the fence and comment state machines over a set of lines to identify regions that should be ignored by other parsers src/vault-mcp/obsidian-markdown/lines.ts203-205

Sources: src/vault-mcp/obsidian-markdown/lines.ts1-7 src/vault-mcp/obsidian-markdown/lines.ts101-154 src/vault-mcp/obsidian-markdown/lines.ts186-201

Task Parsing (tasks.ts)

Vault Cortex provides a faithful reimplementation of the Obsidian Tasks plugin parser. It extracts metadata from checkbox lines using a repeated stripping loop that removes one field at a time from the end of the line src/vault-mcp/obsidian-markdown/tasks.ts5-10

Parity Features

• Dual Format Support: Simultaneously recognizes both Emoji signifiers (e.g., 📅 2026-07-04) and Dataview inline fields (e.g., [due:: 2026-07-04]) src/vault-mcp/obsidian-markdown/tasks.ts11-13
• Status Mapping: Maps checkbox characters to todo, in_progress, done, or cancelled src/vault-mcp/obsidian-markdown/tasks.ts38-40
• Date Fields: Supports all six standard dates: created, scheduled, start, due, done, and cancelled src/vault-mcp/obsidian-markdown/tasks.ts58-63
• Kanban Integration: Captures the nearest preceding heading as the task's heading, which represents the lane on a Kanban board src/vault-mcp/obsidian-markdown/tasks.ts80-82

Sources: src/vault-mcp/obsidian-markdown/tasks.ts1-22 src/vault-mcp/obsidian-markdown/tasks.ts49-83

Heading and Section Parsing (headings.ts)

The heading parser identifies H1 through H6 sections and determines their spans. This logic is shared by both the vault_read_note tool (for outlines) and the vault_patch_note tool (for surgical edits) src/vault-mcp/obsidian-markdown/headings.ts1-6

Key Logic

• Section Spans: A section's body starts after the heading and ends at the next heading of the same or higher level src/vault-mcp/obsidian-markdown/headings.ts138-140 src/vault-mcp/obsidian-markdown/headings.ts200-210
• Kanban/Comment Awareness: findTrailingCommentBlockStart identifies "trailing comment blocks" (e.g., %% kanban:settings %%) so append/replace operations do not clobber plugin metadata src/vault-mcp/obsidian-markdown/headings.ts51-61
• Fence Integration: Headings inside code fences or %% comments are ignored during the single-pass walk src/vault-mcp/obsidian-markdown/headings.ts161-178

Sources: src/vault-mcp/obsidian-markdown/headings.ts1-23 src/vault-mcp/obsidian-markdown/headings.ts134-210

Memory Entry Parsing (memory-entries.ts)

The memory layer uses a specialized parser for the "About Me" dated-bullet format (- **YYYY-MM-DD**: text). This module decomposes topic sections into individual, time-stamped entries src/vault-mcp/obsidian-markdown/memory-entries.ts1-7

• Topic Attribution: Entries are attributed to their enclosing H2 section src/vault-mcp/obsidian-markdown/memory-entries.ts24-27
• Continuation Support: The parser absorbs continuation lines, sub-bullets, and code examples into a single entry's text until a new entry or heading boundary is reached src/vault-mcp/obsidian-markdown/memory-entries.ts33-36 src/vault-mcp/obsidian-markdown/memory-entries.ts87-92
• Index Stability: Entries are assigned a 0-based entryIndex in document order, which is used for content-hash reconciliation in the search index src/vault-mcp/obsidian-markdown/memory-entries.ts38

Sources: src/vault-mcp/obsidian-markdown/memory-entries.ts1-12 src/vault-mcp/obsidian-markdown/memory-entries.ts99-173

Callout and Frontmatter Parsing

Callouts (callouts.ts)

The parseLeadingCallout function extracts the first Obsidian callout block (> [!type]) at the top of a note body src/vault-mcp/obsidian-markdown/callouts.ts1-4 It skips at most one H1 title line to find the callout, which is common in structured memory files src/vault-mcp/obsidian-markdown/callouts.ts6-10

Frontmatter (frontmatter.ts)

Vault Cortex uses gray-matter with a custom yaml engine (YAML 1.2) to prevent the "UTC-Z datetime bug" where timestamp-shaped strings are automatically converted to JS Dates src/vault-mcp/obsidian-markdown/frontmatter.ts5-10

• mergeFrontmatter: Merges updates into existing data. Setting a key to null in the updates object triggers explicit deletion of that property src/vault-mcp/obsidian-markdown/frontmatter.ts66-70

Plaintext Stripping (plaintext.ts)

The stripMarkdownSyntax function produces plain text for the embedding pipeline by removing formatting markers while preserving semantic content src/vault-mcp/obsidian-markdown/plaintext.ts1-4 It strips wikilink brackets (keeping display text), comments, and formatting (bold, italics, callout markers) src/vault-mcp/obsidian-markdown/plaintext.ts6-9

Sources: src/vault-mcp/obsidian-markdown/callouts.ts100-156 src/vault-mcp/obsidian-markdown/frontmatter.ts1-15 src/vault-mcp/obsidian-markdown/plaintext.ts1-27

Canvas Linearization (canvas.ts)

The canvas.ts module provides a JSON Canvas 1.0 linearizer. It converts the spatial JSON format of Obsidian Canvas files into a reading-order string that AI agents can process as text.

• Spatial Sort: Nodes are sorted primarily by their vertical y position, then horizontal x position src/vault-mcp/obsidian-markdown/canvas.ts105-109
• Group Containment: The parser identifies which nodes are spatially contained within "group" nodes, representing this hierarchy in the linearized output src/vault-mcp/obsidian-markdown/canvas.ts111-120
• Edge Resolution: Connections between nodes (edges) are resolved by ID and appended as a list of relationships at the end of the text src/vault-mcp/obsidian-markdown/canvas.ts135-140

Sources: src/vault-mcp/obsidian-markdown/canvas.ts1-20 src/vault-mcp/obsidian-markdown/canvas.ts98-145

Code Entity Map

The following table and diagram map natural language concepts to the specific code entities in the obsidian-markdown/ layer.

Concept	Code Entity	File
Fence State	OpenFence	src/vault-mcp/obsidian-markdown/lines.ts72
Line Normalization	splitIntoLines()	src/vault-mcp/obsidian-markdown/lines.ts16
Wikilink Parsing	splitWikilink()	src/vault-mcp/obsidian-markdown/links.ts151
Section Boundary	HeadingInfo	src/vault-mcp/obsidian-markdown/headings.ts18
Task Extraction	ParsedTask	src/vault-mcp/obsidian-markdown/tasks.ts49
Memory Entry	MemoryEntry	src/vault-mcp/obsidian-markdown/memory-entries.ts24
Canvas Linearizer	linearizeCanvas()	src/vault-mcp/obsidian-markdown/canvas.ts98

Diagram: System Entity Association

Sources: src/vault-mcp/obsidian-markdown/lines.ts72 src/vault-mcp/obsidian-markdown/links.ts151 src/vault-mcp/obsidian-markdown/headings.ts18 src/vault-mcp/obsidian-markdown/tasks.ts49 src/vault-mcp/obsidian-markdown/memory-entries.ts24 src/vault-mcp/obsidian-markdown/canvas.ts98