Ragnar Notes

A local-first Markdown note-taking app for macOS & Linux.
Built with Tauri + React. No cloud lock-in. Your notes, your machine.

---

Table of Contents

• Installation
• Features
• Keyboard Shortcuts
• Architecture
• Tech Stack
• Development
• Testing
• Building
• Contributing
• License

---

Installation

macOS — Download (Recommended)

1. Go to Releases
2. Download the .dmg for your architecture:
   • Apple Silicon (M1/M2/M3/M4): Ragnar.Notes_*_aarch64.dmg
   • Intel: Ragnar.Notes_*_x64.dmg
3. Open the DMG and drag Ragnar Notes into Applications
4. Launch from Applications

Gatekeeper warning: Right-click the app → "Open", or run:

xattr -cr /Applications/Ragnar\ Notes.app

Linux — Download

1. Go to Releases
2. Choose your preferred format:

Debian / Ubuntu (.deb):

sudo dpkg -i ragnar-notes_*.deb
sudo apt-get install -f   # resolve dependencies if needed

AppImage (universal):

chmod +x Ragnar_Notes_*.AppImage
./Ragnar_Notes_*.AppImage

Linux dependencies: The .deb package declares its dependencies automatically. For AppImage or building from source, ensure you have: libwebkit2gtk-4.0-37, libgtk-3-0, libayatana-appindicator3-1

Build from Source

macOS — Requires macOS 12+, Node.js 18+, Rust stable, and Xcode CLI tools.

git clone https://github.com/VidhyadharanSS/RagnarNotes.git
cd RagnarNotes
npm install
npm run tauri build

Linux — Requires Node.js 18+, Rust stable, and system libraries.

# Install system dependencies (Debian/Ubuntu)
sudo apt-get update
sudo apt-get install -y \
  libwebkit2gtk-4.0-dev \
  libgtk-3-dev \
  libayatana-appindicator3-dev \
  librsvg2-dev \
  patchelf

# Clone and build
git clone https://github.com/VidhyadharanSS/RagnarNotes.git
cd RagnarNotes
npm install
npm run tauri build

Build outputs:

Platform	Location
macOS	src-tauri/target/release/bundle/dmg/*.dmg
Linux .deb	src-tauri/target/release/bundle/deb/*.deb
Linux AppImage	src-tauri/target/release/bundle/appimage/*.AppImage

---

Features

✏️ Editor

• Full GitHub Flavored Markdown — tables, task lists, footnotes, callouts
• Syntax highlighting for 150+ languages via highlight.js
• Split view — Edit + Preview side-by-side with synchronized scrolling
• Zen / Focus mode — distraction-free writing with ambient sounds, breathing guide, and session timer
• Smart Enter — auto-continues lists, tasks, blockquotes
• Slash commands (/heading, /table, /code, /callout, etc.)
• [[ Wiki-link autocomplete — type [[ to fuzzy-search and link to other notes
• Undo/Redo with full snapshot history
• Inline emoji picker
• Callout blocks: > [!NOTE], > [!WARNING], > [!TIP]

📝 Notes

• Pin notes to top
• Color labels — 8 colors for visual organization
• Tags with Obsidian-style inline #tag suggestions
• Move notes between folders via right-click
• Bulk select for trash/delete/export
• Import individual files or entire folders of .md files
• Duplicate notes
• Hover preview cards

📁 Folders

• Nested folder hierarchy with subfolder support
• Right-click context menu: Rename, Create Subfolder, Delete
• Drag-friendly folder tree with expand/collapse

🧠 Organization & Knowledge

• Knowledge graph — visual map of note connections with PageRank, community detection, pan/zoom, and tag filtering
• Note templates — 8 prebuilt templates (Meeting, Journal, Project, etc.)
• Backlinks panel — see which notes link to the current note
• Outline panel — heading-based document structure
• Floating Table of Contents — collapsible minimap that shows all headings, click to jump to any section
• Note history panel
• Bookmarks bar for quick access
• Quick Switcher for rapid note navigation (⌘O)
• Command Palette (⌘K) — search commands, notes, and actions

📊 Writing Analytics

• Word Frequency Cloud — interactive tag cloud visualizing your most-used words
• Reading Stats Bar — Flesch readability score, reading level, grade level, vocabulary richness
• Writing Activity Sparkline — 7-day activity chart in the sidebar
• Quick Stats — total notes, pinned, today's edits, writing streak
• Session Timer — tracks how long you've been writing (visible in status bar)
• Pomodoro Timer — fully editable with work/break/rounds configuration

📤 Export

• PDF, Markdown, HTML export per note
• Bulk export — select multiple notes and export all at once (as individual files or ZIP)
• Code block copy with visual "Copied" feedback

☁️ Google Drive Sync

• OAuth 2.0 with PKCE for secure authentication
• Two-way sync with conflict resolution
• Selective sync per folder
• Sync status indicators throughout the UI

🎨 Appearance

• 8 themes: Dark, Light, System, Rosé Pine, Nord, Catppuccin, Gruvbox, Solarized
• 14 font families across Sans-serif, Serif, and Monospace
• 10 accent colors
• Adjustable font size, line height, editor width
• Resizable sidebar and note list panels
• Full-screen reading and editing mode

⚙️ Settings

• Auto-save with configurable delay (0.5s–10s)
• Spell check toggle
• Compact mode
• Word count in status bar
• Storage manager with usage info
• In-app update checker (checks GitHub releases)

---

Keyboard Shortcuts

Shortcut	Action
⌘K	Command Palette / Search
⌘O	Quick Switcher
⌘N	New Note
⌘,	Settings
⌘/	Toggle Sidebar
⌘.	Zen / Focus Mode
⌘E	Edit Mode
⌘⇧P	Preview Mode
⌘⇧S	Split View
⌘⇧E	Export Note
⌘F	Find in Note
⌘Z	Undo
⌘⇧Z	Redo
⌘B	Bold
⌘I	Italic
⌘`	Inline Code
⌘⇧X	Strikethrough
⌘⇧H	Highlight

On Linux, replace ⌘ with Ctrl.

---

Architecture

src/
├── components/
│   ├── editor/         MarkdownEditor, EditorToolbar, EditorSidePanel,
│   │                   MarkdownPreview, StatusBar
│   ├── features/       CommandPalette, ExportModal, BulkExportModal, SettingsPanel,
│   │                   NoteTemplates, NoteGraph, FolderTree, QuickSwitcher,
│   │                   WikiLinkSuggestion, FloatingTOC, FocusTimer,
│   │                   CloudSyncPanel, WritingAnalytics, SmartInsights, ...
│   ├── layout/         Sidebar, NoteList, EditorPane, TitleBar, ResizeHandle
│   ├── onboarding/     VaultPicker
│   └── ui/             Toast, Tooltip, ContextMenu, HoverPreview, NoteColorPicker,
│                       ProgressBar, ReadingProgress, SyncStatusIndicator
├── hooks/              useTheme, useAutoSave, useKeyboardShortcut, useResizable,
│                       useUndoRedo, useClickOutside, useDebounce, useGoogleDriveSync
├── stores/             appStore, editorStore, notesStore, searchStore, syncStore (Zustand)
├── services/           googleDrive.ts (Drive API client)
├── utils/              format, sanitize, keyboard, markdown, fonts, exportPdf,
│                       graphAlgorithm, nlp, search, cn
├── styles/             globals.css (design tokens, prose, theme variables),
│                       highlight.css
├── lib/                seedData, tauri (API bridge)
└── types/              index.ts, type declarations

src-tauri/
├── src/
│   ├── main.rs         Tauri entry point, command handler registration
│   ├── lib.rs          Library crate root (for clippy --all-targets)
│   ├── error.rs        Unified AppError type with CmdResult alias
│   ├── models.rs       Rust ↔ TypeScript data models (Note, Folder, Vault)
│   └── commands/
│       ├── mod.rs      Module declarations
│       ├── fs.rs       File system: read/write/create/delete notes & folders,
│       │               bulk move, recursive folder import
│       ├── app.rs      App version, vault dialog, fetch_url (CORS bypass)
│       └── gdrive.rs   Google Drive OAuth2 with PKCE (Desktop flow)
├── build.rs            Compile-time secret injection from .env.secrets
├── Cargo.toml          Rust dependencies
├── tauri.conf.json     Tauri app configuration (macOS + Linux bundles)
└── Entitlements.plist  macOS entitlements for ad-hoc signing

---

Tech Stack

Layer	Technology
Shell	Tauri 1.6 (Rust) — native macOS & Linux
Frontend	React 18, TypeScript 5 (strict mode)
Styling	Tailwind CSS 3, CSS custom properties
Animations	Framer Motion 11
State	Zustand 4 (devtools + persist middleware)
Markdown	marked (GFM) + custom renderer
Syntax	highlight.js
PDF	html2pdf.js
NLP	compromise.js
Archive	JSZip
HTTP	reqwest (Rust), fetch (browser)
Testing	Vitest + @testing-library/react
Build	Vite 5, tauri-build
CI/CD	GitHub Actions (lint → test → clippy → build → release)

---

Development

Prerequisites

• Node.js 18+ and npm
• Rust stable (1.70+) via rustup
• macOS: Xcode Command Line Tools (xcode-select --install)
• Linux: System libraries:

  sudo apt-get install -y \
    libwebkit2gtk-4.0-dev \
    libgtk-3-dev \
    libayatana-appindicator3-dev \
    librsvg2-dev

Setup

git clone https://github.com/VidhyadharanSS/RagnarNotes.git
cd RagnarNotes
npm install

Run

npm run dev           # Web preview at http://localhost:1420
npm run tauri dev     # Native window with hot-reload

Code Quality

npm run lint          # ESLint (0 errors, 0 warnings)
npm run lint:fix      # Auto-fix ESLint issues
npm run typecheck     # TypeScript strict type-checking
npm run format        # Prettier formatting

# Rust
cd src-tauri
cargo clippy --all-targets --all-features -- -D warnings
cargo fmt --all -- --check

---

Testing

npm test              # 256 tests across 12 suites
npm run test:watch    # Watch mode
npm run test:coverage # Coverage report

Test suites cover:

• Stores: appStore, editorStore, notesStore, searchStore, syncStore
• Features: noteGraph (PageRank, community detection, layout)
• Services: googleDrive (OAuth flow, token management)
• Utils: cn, format, keyboard, markdown, sanitize

---

Building

macOS

# Universal (host architecture)
npm run tauri build

# Target-specific
npm run tauri build -- --target aarch64-apple-darwin   # Apple Silicon
npm run tauri build -- --target x86_64-apple-darwin     # Intel

Linux

npm run tauri build

Produces both .deb (Debian/Ubuntu) and .AppImage (universal) packages in:

• src-tauri/target/release/bundle/deb/
• src-tauri/target/release/bundle/appimage/

CI/CD Pipeline

The GitHub Actions workflow (.github/workflows/main.yml) runs:

1. 🔍 Lint & Type Check — ESLint + TypeScript strict mode (ubuntu-latest)
2. 🧪 Unit Tests — 256 tests with coverage (ubuntu-latest)
3. 🦀 Rust Clippy — zero-warning policy + cargo fmt check (ubuntu-latest)
4. 🏗️ Build macOS App — on push to main (macos-latest)
5. 🐧 Build Linux App — .deb + AppImage on push to main (ubuntu-22.04)
6. 🚀 Release — on version tags (v*.*.*):
   • Builds macOS (Apple Silicon + Intel) with ad-hoc codesigning
   • Builds Linux (x86_64) with .deb and AppImage
   • Publishes all artifacts to GitHub Releases

Google Drive OAuth Setup

For builds that include Google Drive sync:

1. Create a Desktop OAuth 2.0 client in Google Cloud Console
2. Copy the Client Secret
3. Local dev: Create src-tauri/.env.secrets:

   GOOGLE_CLIENT_SECRET=GOCSPX-your-secret-here
   

4. CI: Set the GOOGLE_CLIENT_SECRET repository secret in GitHub

The build.rs script injects the secret at compile time. For non-release builds (clippy, check), a placeholder is used automatically.

---

Contributing

1. Fork the repository
2. Create a feature branch: git checkout -b feature/my-feature
3. Make your changes
4. Run the full quality check:

   npm run lint && npm run typecheck && npm test
   cd src-tauri && cargo clippy --all-targets -- -D warnings && cargo fmt --check

5. Commit with a descriptive message
6. Push and open a Pull Request

---

License

MIT — Vidhya Dharan S S