Markdown Viewer Development Guide

A comprehensive guide for developing a lightweight, cross-platform markdown viewer application using Tauri, Rust, and TypeScript.

Project Overview

You are working on a markdown viewer application designed to be a lightweight, cross-platform tool for reading markdown files. The primary use case is displaying markdown content in a scrollable window that can be used as a reference while working in other applications.

Key Project Characteristics

When working on this project, keep these principles in mind:

Technology Stack

Architecture Guidelines

Backend (Rust)

Use simple Tauri commands for file operations:

```rust

#[tauri::command]

async fn open_file(path: String) -> Result<String, String>

#[tauri::command]

async fn check_file_already_open(path: String) -> Result<bool, String>

#[tauri::command]

async fn activate_existing_window(path: String) -> Result<(), String>

```

**Key patterns:**

Frontend (TypeScript)

**Component structure:**

**Module organization:**

**State management:**

```typescript

interface WindowState {

currentFile: string | null;

fileContent: string;

searchResults: SearchResult[];

settings: AppSettings;

}

```

Single-Instance-Per-File Architecture

Project Structure

```

src-tauri/ # Rust backend

├── src/

│ ├── main.rs

│ ├── commands/ # Tauri commands

│ ├── file/ # File operations & watching

│ └── instance/ # Single-instance management

├── Cargo.toml

└── tauri.conf.json

src/ # Frontend

├── components/ # UI component classes

├── modules/ # Business logic modules

├── types/ # TypeScript interfaces

├── styles/ # CSS styling

├── index.html

└── tsconfig.json

```

MVP Development Plan

MVP Scope (Phase 1)

**Include in MVP:**

**Defer to Phase 2:**

Development Phases

**Phase 1: Project Setup**

1. Initialize Tauri project with TypeScript

2. Set up build pipeline and development environment

3. Create basic window structure and file organization

4. Test cross-platform development setup

*Milestone 1:* "Hello World" - Tauri app opens with basic window

**Phase 2: Core Functionality**

1. Implement file opening (dialog + CLI arguments)

2. Set up markdown-it parsing pipeline

3. Basic HTML rendering and content display

4. Ensure text selection works properly

*Milestone 2:* "File Operations" - Can open and display markdown files

**Phase 3: Polish & Distribution**

1. Implement single instance per file logic

2. Add syntax highlighting with Prism.js

3. Basic styling, layout, and user experience polish

4. Cross-platform build scripts and packaging

*Milestone 3:* "Production Ready" - Fully functional MVP ready for distribution

Success Criteria

The MVP is complete when:

Post-MVP Features (Phase 2)

After MVP completion, implement these features:

Development Commands

```bash

Development mode

cargo tauri dev

Production build

cargo tauri build

Run tests

cargo test

TypeScript compilation and tests

npm run build

npm test

```

Git Commit Guidelines

When committing changes to this project:

Examples

**Good commit:**

```bash

git commit -m "Add file dialog for opening markdown files" \

-m "Implement native file dialog using Tauri's dialog API. Supports .md and .markdown extensions. Task #2.1"

```

**Good branch name:**

```

feature/syntax-highlighting

fix/window-activation-bug

refactor/markdown-parser

```

Important Constraints

1. **No editing features**: This is a viewer-only application

2. **One document per window**: Each window manages exactly one file

3. **Performance first**: Keep the application lightweight and fast

4. **Cross-platform**: All features must work on Windows, macOS, and Linux

5. **Incremental updates**: Use diffing to update content without losing scroll position or selection

Getting Started

1. Ensure you have Rust and Node.js installed

2. Review `requirements.md` for detailed feature specifications

3. Follow the MVP Development Plan phases in order

4. Test on all target platforms regularly

5. Keep commits focused and well-documented