MDReader

A streamlined, offline-first markdown note-taking and organization application built with Flutter. Think Obsidian, but more focused and extensible.

Features

• Local markdown file management
• Real-time markdown preview
• Offline-first architecture
• Cross-platform (Linux desktop + Android)
• Fast and responsive UI
• Extensible for future features

Architecture

See ARCHITECTURE.md for detailed technical documentation and development roadmap.

Prerequisites

• Flutter SDK (3.0 or higher)
• Dart SDK (included with Flutter)
• Linux development setup OR Android development setup

Installation

1. Install Flutter SDK

On Linux:

# Download Flutter SDK
cd ~
git clone https://github.com/flutter/flutter.git -b stable

# Add Flutter to PATH (add to ~/.bashrc or ~/.zshrc)
export PATH="$PATH:$HOME/flutter/bin"

# Reload shell configuration
source ~/.bashrc  # or source ~/.zshrc

# Verify installation
flutter doctor

2. Install Linux Desktop Dependencies

# Ubuntu/Debian
sudo apt-get update
sudo apt-get install -y \
  clang \
  cmake \
  ninja-build \
  pkg-config \
  libgtk-3-dev \
  liblzma-dev

# Fedora
sudo dnf install -y \
  clang \
  cmake \
  ninja-build \
  pkg-config \
  gtk3-devel \
  xz-devel

3. Enable Linux Desktop Support

flutter config --enable-linux-desktop

4. Verify Setup

flutter doctor
# Should show Linux desktop and Android (if configured) as available

Development Setup

1. Clone and Setup

cd /home/user/mdreader
flutter pub get

2. Run on Linux Desktop

flutter run -d linux

3. Run on Android (requires Android device/emulator)

flutter devices  # List available devices
flutter run -d <device-id>

Project Structure

mdreader/
├── lib/
│   ├── main.dart              # App entry point
│   ├── core/                  # Core utilities, constants, theme
│   ├── features/              # Feature modules
│   │   ├── file_browser/
│   │   ├── note_editor/
│   │   ├── note_viewer/
│   │   └── search/
│   └── shared/                # Shared widgets and providers
├── test/                      # Unit and widget tests
├── integration_test/          # Integration tests
├── linux/                     # Linux platform code
├── android/                   # Android platform code
└── assets/                    # Images, fonts, etc.

Development Roadmap

Phase 1: MVP (Current)

• Architecture planning
• Project initialization
• Basic file browser
• Simple note editor
• Markdown rendering
• File operations (CRUD)

Phase 2: Core Features

• Search functionality
• Split view (edit + preview)
• Auto-save
• Settings screen
• Themes (light/dark)

Phase 3: Advanced Features

• Tags system
• Backlinks
• Graph view
• Full-text search
• Export functionality

Phase 4: Mobile & Polish

• Android optimization
• Mobile gestures
• Performance tuning
• Advanced theming

Building

Linux

flutter build linux
# Output: build/linux/x64/release/bundle/

Android

flutter build apk
# Output: build/app/outputs/flutter-apk/app-release.apk

Testing

# Run all tests
flutter test

# Run with coverage
flutter test --coverage

# Run integration tests
flutter test integration_test/

Contributing

This is a personal project, but suggestions and feedback are welcome!

Tech Stack

• Framework: Flutter
• Language: Dart
• State Management: Riverpod
• Local Storage: SQLite (sqflite) + Shared Preferences
• Markdown: flutter_markdown
• File System: dart:io + path_provider

License

MIT License (to be added)

Acknowledgments

Inspired by:

• Obsidian
• Notion
• Notable
• Joplin

---

Status: In Development Version: 0.1.0-alpha Last Updated: 2025-10-24