stack/apps/api/src/knowledge/utils

Knowledge Module Utilities

Wiki-Link Parser

Overview

The wiki-link-parser.ts utility provides parsing of wiki-style [[links]] from markdown content. This is the foundation for the Knowledge Module's linking system.

Features

• Multiple Link Formats: Supports title, slug, and display text variations
• Position Tracking: Returns exact positions for link replacement or highlighting
• Code Block Awareness: Skips links in code blocks (inline and fenced)
• Escape Support: Respects escaped brackets \[[not a link]]
• Edge Case Handling: Properly handles nested brackets, empty links, and malformed syntax

Usage

import { parseWikiLinks } from './utils/wiki-link-parser';

const content = 'See [[Main Page]] and [[Getting Started|start here]].';
const links = parseWikiLinks(content);

// Result:
// [
//   {
//     raw: '[[Main Page]]',
//     target: 'Main Page',
//     displayText: 'Main Page',
//     start: 4,
//     end: 17
//   },
//   {
//     raw: '[[Getting Started|start here]]',
//     target: 'Getting Started',
//     displayText: 'start here',
//     start: 22,
//     end: 52
//   }
// ]

Supported Link Formats

Basic Link (by title)

[[Page Name]]

Links to a page by its title. Display text will be "Page Name".

Link with Display Text

[[Page Name|custom display]]

Links to "Page Name" but displays "custom display".

Link by Slug

[[page-slug-name]]

Links to a page by its URL slug (kebab-case).

Edge Cases

Nested Brackets

[[Page [with] brackets]]  ✓ Parsed correctly

Single brackets inside link text are allowed.

Code Blocks (Not Parsed)

Use `[[WikiLink]]` syntax for linking.

\`\`\`typescript
const link = "[[not parsed]]";
\`\`\`

Links inside inline code or fenced code blocks are ignored.

Escaped Brackets

\[[not a link]] but [[real link]] works

Escaped brackets are not parsed as links.

Empty or Invalid Links

[[]]           ✗ Empty link (ignored)
[[   ]]        ✗ Whitespace only (ignored)
[[  Target  ]] ✓ Trimmed to "Target"

Return Type

interface WikiLink {
  raw: string;        // Full matched text: "[[Page Name]]"
  target: string;     // Target page: "Page Name"
  displayText: string; // Display text: "Page Name" or custom
  start: number;      // Start position in content
  end: number;        // End position in content
}

Testing

Comprehensive test suite (100% coverage) includes:

• Basic parsing (single, multiple, consecutive links)
• Display text variations
• Edge cases (brackets, escapes, empty links)
• Code block exclusion (inline, fenced, indented)
• Position tracking
• Unicode support
• Malformed input handling

Run tests:

pnpm test --filter=@mosaic/api -- wiki-link-parser.spec.ts

Integration

This parser is designed to work with the Knowledge Module's linking system:

1. On Entry Save: Parse [[links]] from content
2. Create Link Records: Store references in database
3. Backlink Tracking: Maintain bidirectional link relationships
4. Link Rendering: Replace [[links]] with HTML anchors

See related issues:

• #59 - Wiki-link parser (this implementation)
• Future: Link resolution and storage
• Future: Backlink display and navigation

Markdown Rendering

Overview

The markdown.ts utility provides secure markdown rendering with GFM (GitHub Flavored Markdown) support, syntax highlighting, and XSS protection.

Features

• GFM Support: Tables, task lists, strikethrough, autolinks
• Syntax Highlighting: Code blocks with language detection via highlight.js
• XSS Protection: HTML sanitization using sanitize-html
• Header IDs: Automatic ID generation for headers (for linking)
• Security: Blocks dangerous HTML (scripts, iframes, event handlers)

Usage

import { renderMarkdown, markdownToPlainText } from './utils/markdown';

// Render markdown to HTML (async)
const html = await renderMarkdown('# Hello **World**');
// Result: <h1 id="hello-world">Hello <strong>World</strong></h1>

// Extract plain text (for search indexing)
const plainText = await markdownToPlainText('# Hello **World**');
// Result: "Hello World"

Supported Markdown Features

Basic Formatting

• Bold: **text** or __text__
• Italic: *text* or _text_
• Strikethrough: ~~text~~
• Inline code: `code`

Headers

# H1
## H2
### H3

Lists

- Unordered list
  - Nested item

1. Ordered list
2. Another item

Task Lists

- [ ] Unchecked task
- [x] Completed task

Tables

| Header 1 | Header 2 |
|----------|----------|
| Cell 1   | Cell 2   |

Code Blocks

```typescript
const greeting: string = "Hello";
console.log(greeting);
```

Links and Images

[Link text](https://example.com)
![Alt text](https://example.com/image.png)

Blockquotes

> This is a quote
> Multi-line quote

Security

The renderer implements multiple layers of security:

1. HTML Sanitization: Only allows safe HTML tags and attributes
2. URL Validation: Blocks javascript: and other dangerous protocols
3. External Links: Automatically adds target="_blank" and rel="noopener noreferrer"
4. Task Lists: Checkboxes are disabled to prevent interaction
5. No Event Handlers: Blocks onclick, onload, etc.
6. No Dangerous Tags: Blocks <script>, <iframe>, <object>, <embed>

Testing

Comprehensive test suite covers:

• Basic markdown rendering
• GFM features (tables, task lists, strikethrough)
• Code syntax highlighting
• Security (XSS prevention)
• Edge cases (unicode, long content, nested structures)

Run tests:

pnpm test --filter=@mosaic/api -- markdown.spec.ts

Integration

The markdown renderer is integrated into the Knowledge Entry service:

1. On Create: Renders content to contentHtml
2. On Update: Re-renders if content changes
3. Caching: HTML is stored in database for performance

See knowledge.service.ts for implementation details.