v2.3.0 · Free & Open Source · MIT License

Research notes,
finally organised.

Noteration is a free, open-source desktop app for academic researchers. Write in Markdown, annotate PDFs, manage your literature library with Papis, explore your wiki-link graph, and sync everything to GitHub — all without switching apps.

↓ Install Now View Source
Python 3.11+ PySide6 GUI Linux · macOS · Windows License MIT
bash — noteration vault
# Install in one line $ curl -fsSL https://raw.githubusercontent.com/
  lilamr/noteration/main/install.sh | bash   ==> Creating virtual environment... ==> Installing Noteration... ✓ Noteration v2.3.0 installed!   $ noteration
thesis-outline.md literature.py
# Chapter 2 — Methodology   See [[sampling-framework]] for detailed rationale. As noted by @creswell2014 the approach is **purposive sampling**, which *ensures theoretical depth*.
Features

Every tool a researcher needs, in one desktop app

Noteration was designed around a single principle: the academic research workflow should not be spread across five different apps. Markdown notes, PDF papers, citations, backlink graphs, and version control — integrated and always in sync.

✎

Markdown Editor

A distraction-free Markdown editor with full syntax highlighting, line numbers, auto-indent, and support for LaTeX. Write naturally and switch to rendered view with one keypress.

Ctrl+Shift+V
◫

Split View

Work on two notes at once or read a PDF side-by-side with your research draft. Noteration 2.0 introduces vertical splitting to maximise your screen real estate and research productivity.

New in v2.0
🕸️

Wiki-links & Knowledge Graph

Connect notes with [[wiki-link]] syntax. Navigate with Ctrl+Click. An interactive force-directed graph visualises your entire knowledge network and highlights orphan notes.

NetworkX
📘

PDF Viewer & Annotations

Read research papers without leaving the app. Highlight text, add sticky notes, and capture image regions — all stored as non-destructive JSON annotations, synced to GitHub alongside your notes.

PyMuPDF
📚

Literature Management

Browse your Papis reference library inside Noteration. Auto-fetch metadata from DOI. Export BibTeX per-note or choose from thousands of CSL citation styles (APA, IEEE, etc).

Papis + CSL
🔍

Global Vault Search

High-performance SQLite FTS5 engine that covers all notes, literature metadata, and PDF annotations. Get instant results even in massive vaults with regex and case-sensitive support.

FTS5 Engine
☁️

GitHub Sync

Commit, pull, and push your vault to any Git remote. Choose from three merge strategies — rebase, merge, or stash. A built-in three-panel conflict resolution dialog handles merge conflicts visually.

GitPython
🎨

Dark, Light & System Theme

A full theme engine with light, dark, and OS-adaptive modes. Theme changes apply live while you adjust settings — press Cancel at any time to instantly revert to the previous theme.

PySide6
🧘

Focus Mode

Press F11 for a fullscreen, distraction-free writing environment. All UI hides, the editor centres itself, and Vim keybindings activate so you never need to leave the keyboard.

Vim Support
📤

Document Export

Easily share your research in the format you need. Export Markdown notes directly to HTML, PDF, DOCX, ODT, LaTeX, or plain text with just a few clicks.

Pandoc Powered
#

Tags Management

Organise your knowledge with a unified #tag system. Noteration synchronises tags between your Markdown notes and Papis literature metadata for a truly integrated workflow.

Unified Search
∑

Advanced Rendering

Academic-grade LaTeX support via Arithmatex. Render complex formulae directly in your preview.

New in v2.0
🛡️

Vault Encryption

At-rest encryption using the age format, natively integrated for seamless security. Secure your entire research vault with public-key cryptography and a seamless session decryption workflow. Encryption can be permanently disabled at any time through settings.

New in v2.0
>_

Powerful CLI

Manage your vault, search notes, fetch literature, and sync changes directly from your terminal with the ntr command. Perfect for automation and power users.

New in v2.0
🌐

REST API

Expose your vault via a lightweight HTTP interface. Integrate Noteration with external tools like Obsidian, VS Code, or custom scripts using standard JSON endpoints.

New in v2.0
How It Works

How Noteration organises your research workflow

Everything lives in a single, portable folder called a Vault. It is plain text, version-controlled, and fully readable without Noteration — your research data is always yours.

01

Create or open a research Vault

A Vault is a plain folder on your computer. Noteration adds .noteration/config.toml for settings, then you populate notes/, literature/, and attachments/ as you work.

02

Read PDFs and create non-destructive annotations

Open any research paper in the built-in PDF viewer. Highlight key passages, add margin notes — none of it modifies the original PDF. All annotations are stored as portable JSON files.

03

Write Markdown notes with wiki-links and citations

In your Markdown note, type [[ to link another note, or @ to autocomplete a citation key from your Papis library. The backlink graph updates automatically.

04

Sync your vault to GitHub

One click - Noteration commits, pulls, and pushes. Your entire research vault is backed up and accessible on any device.

~/research-vault/
├── .noteration/     ├── config.toml # settings (synced ✓)     ├── link_graph.json # cache (local only)     └── db.sqlite # index (local only)   ├── notes/ # Markdown (synced ✓)     ├── index.md     ├── methodology.md     └── results/         └── chapter-3.md   ├── literature/ # Papis library     └── creswell2014/         ├── info.yaml # metadata (synced ✓)         └── creswell2014.pdf # large (local only)   ├── annotations/ # JSON (synced ✓)     └── <sha256>.json   └── attachments/ # assets (synced ✓)     └── diagram.png   ✓ git remote: github.com/you/vault
Screenshots

See Noteration in action

From the distraction-free Focus Mode with Vim keybindings to the interactive knowledge graph — every panel in Noteration is designed for deep, sustained research work. Click a tab to explore each feature.

Noteration main editor — Markdown editing with sidebar, wiki-links, citations, and backlink panel
✎
images/screenshot-editor.png
Replace with your actual screenshot
Main editor — syntax highlighting, wiki-links (purple), citations (green), backlink panel on the right
Split View — side-by-side editing and reading
◫
images/screenshot-split.png
Replace with your actual screenshot
Split View (v2.0) — vertical layout for multi-tasking. Move any tab between left and right panes using the tab context menu.
Focus Mode — fullscreen distraction-free writing with Vim keybindings
🧘
images/screenshot-focus.png
Replace with your actual screenshot
Focus Mode (F11) — all UI hidden, centered editor, Vim keybindings active (NORMAL · INSERT · VISUAL · COMMAND)
PDF Viewer — highlight annotations, reading progress, and annotation panel
📘
images/screenshot-pdf.png
Replace with your actual screenshot
PDF viewer — highlight mode active, non-destructive JSON annotations, reading progress tracker, insert-to-editor button
Backlink Graph — interactive force-directed visualization of wiki-link network
🕸️
images/screenshot-graph.png
Replace with your actual screenshot
Interactive backlink graph — orange = active note, blue = linked notes, grey = orphans
Literature tab — Papis library browser with metadata, tags, and BibTeX export
📚
images/screenshot-literature.png
Replace with your actual screenshot
Literature tab — Papis library browser with search, full metadata detail panel, tag management, and BibTeX preview
Git Sync — visual conflict resolution and synchronization status
☁️
images/screenshot-sync.png
Replace with your actual screenshot
GitHub Sync — one click commit/pull/push, sync status indicator, and visual three-panel conflict resolution
Installation

Install Noteration in under a minute

Choose your platform. Each one-liner creates a virtual environment, installs all Python dependencies, and adds a desktop shortcut. Requires Python 3.11+ and Git.

🐧

Linux

↓ Download .deb (x64)
or install via CLI
curl -fsSL https://raw.githubusercontent.com/lilamr/noteration/main/install.sh | bash

Creates a .desktop entry in your applications menu. Requires Python 3.11+, Git, and python3-venv.

🍎

macOS

↓ Download .dmg
or install via CLI
curl -fsSL https://raw.githubusercontent.com/lilamr/noteration/main/install.sh | bash

Creates Noteration.app in ~/Applications with a proper icon — visible in Launchpad.

🪟

Windows

↓ Download .exe (x64)
or install via CLI
irm https://raw.githubusercontent.com/lilamr/noteration/main/install.ps1 | iex

Run in PowerShell. Creates a Desktop shortcut and a Start Menu entry. No admin rights required.

Manual / Development
# Clone and install for development $ git clone https://github.com/lilamr/noteration.git $ cd noteration $ pip install -e ".[all]" $ python -m noteration
Changelog

Release history

Noteration follows Keep a Changelog. Every release is tagged on GitHub with a full list of new features, changes, and fixes.

Versions

v2.3.0

2026-06-22
latest
Added
  • Restore Last Session — The application now remembers and restores the tabs (Editor, PDF, Literature, Sync) that were active when you last closed the app.
Fixed
  • Terminal Hang on Exit — Sync threads now have a safe-terminate escalation to ensure graceful shutdown without requiring Ctrl+C.
  • Auto-restart Instability — The application no longer forces an auto-restart after enabling or disabling vault encryption, preventing initialization race conditions.
  • Uncommitted Modifications on Exit — The app now guarantees a local commit during the shutdown sequence of encrypted vaults without triggering network blocks.
Changed
  • UI Consistency (Tab Architecture) — Introduced a polymorphic base class (NoterationTab) across all tab types.
  • UI Consistency (Toolbars) — Standardized the action buttons in Literature, PDF Viewer, and Sync tabs to use native QToolBar and QAction.

v2.2.0

2026-06-18
Added
  • Standardize background tasks — Introduced BaseWorker class to standardize background tasks and signal handling.
Fixed
  • Asynchronous PDF Rendering — PDF pages are now rendered asynchronously in a background thread.
Changed
  • Architectural Refactoring — Decomposed massive editor_tab.py into focused modules.
  • API Routing — Migrated the REST API to use FastAPI's APIRouter for better modularity.

v2.1.0

2026-06-11
Added
  • Citation Locators — Added support for citation locators (e.g., @key[p.10]) in Markdown editor.
  • Deep Linking — Clicking literature search results or right-clicking citations in the sidebar now opens and focuses the Literature tab directly to the target document.
  • Search Dialog Behavior — The search dialog now remains open after selecting a result, allowing for continuous searching without re-opening.
Changed
  • Citations context — New menu streamlined to show 'Open Literature'.
  • Standalone installer — GitHub Actions release workflow now builds .deb, .exe, and .dmg installers.

v2.0.0

2026-06-03
Added
  • Command Line Interface (ntr) — full vault management, FTS search, literature fetching, and sync from the terminal.
  • REST API (ntr-api) — FastAPI-based HTTP interface for external tool integration.
  • API Security — configurable API Key authentication for secure remote access.
  • GUI API Control — new tab in Settings to manage server lifecycle and authentication.
  • Advanced CLI Export — integrated Pandoc-based export directly into the CLI.
  • Architectural Decoupling — refactored core logic into VaultCore (Pure Python), separating business rules from GUI.
  • SQLite FTS5 Search — high-performance full-text search engine for notes and literature.
  • Tags System — first-class #tag support with automatic extraction and dedicated sidebar panel.
  • Split View — vertical layout for side-by-side editing and reading.
  • Robust LaTeX — integrated Arithmatex for reliable math rendering in the preview.
  • Vault Encryption — "at-rest" encryption using age with a secure session workflow.
  • Navigation History — browser-style back/forward navigation (Alt+Left/Right).
  • PDF Annotation Toggle — show/hide the annotation panel with a dedicated shortcut (Ctrl+Alt+A).
  • Detailed Sync Logs — specific changed and untracked files are now listed in the Synchronization tab.
Changed
  • CSL Selection — users can now choose preferred citation styles (APA, IEEE, etc.) in Settings.
  • Export Flow — unified and simplified document export menus across the application.

v1.2.0

2026-05-16
Added
  • Thread Safety — implemented global RLock across all data engines to prevent race conditions.
  • Data Integrity — added Atomic Write pattern for all JSON and TOML storage.
  • Memory Management — new Cost-Based LRU Cache (250MB limit) for high-resolution PDF rendering.
  • Robust Shutdown — improved orchestration with blocking wait and early-exit support.
Changed
  • Architecture — decoupled VaultManager into specialized controllers for better maintainability.
  • Papis Integration — standardized YAML-read/CLI-write path, removing unstable Python API dependencies.

v1.1.2

2026-05-10
Fixed
  • Stability — fixed critical crashes in background thread management using robust object validity checks.
  • Git Sync — resolved infinite rebase loops by auto-resolving log file conflicts and improving .gitignore enforcement.
  • Git Sync — fixed Segmentation Fault when handling extremely large conflict files.
  • Performance — refactored status refreshes to be fully non-blocking, ensuring a smooth UI experience during network calls.
Added
  • Sync Indicators — new visual status labels showing "Ahead" (pending push) and "Behind" (pending pull) commit counts.
Removed
  • Git Auto-sync — now git synchronization is fully manual.

v1.1.1

2026-05-06
Fixed
  • Git Sync — resolved repository state detection issues and improved robustness when syncing with new/empty remotes.
  • Branch Auto-detection — fixed branch mismatch by dynamically detecting the active local branch (e.g., master) instead of using hardcoded defaults.
  • UI Performance — eliminated application lag by removing synchronous network calls from the status bar update logic.
  • UX Improvements — new notes created from the sidebar now open automatically in the editor.
  • Config & Metadata — refined Git status to ignore internal metadata and fixed a shared state bug in vault settings.
Changed
  • Default Settings — Auto Sync is now disabled by default to improve performance and give users more control over network activity.

v1.1.0

2026-05-04
Added
  • Focus Mode (F11) — fullscreen, distraction-free writing environment: all UI panels hide, the Markdown editor centres at 50% screen width for a calm writing experience.
  • Vim Keybindings — Normal, Insert, Visual, and Line-Visual modes active inside Focus Mode. Command field supports :w (save), :q (exit Focus), and :wq (save and exit).
  • Research & Writing Guide (F2) — built-in academic writing reference covering critical reading, citation ethics, argumentation, and discipline-specific documentation standards.
  • Check for Updates — silent background version check against GitHub Releases; one-click update via pip with auto-restart on all platforms.
  • One-liner installers — install.sh for Linux and macOS (with .desktop entry and app icon), and install.ps1 for Windows PowerShell.
  • App icon assets — PNG and ICNS at 16, 32, 48, 128, 256, and 512 px for cross-platform desktop integration.
  • Global Ctrl+N / Ctrl+S — keyboard shortcuts now work inside Focus Mode and all other contexts.
Changed
  • HelpDialog refactored — now generic; accepts any Markdown filename from noteration/docs/, making it easy to ship new in-app reference guides.

v1.0.0

2026-04-30
Initial Release
  • Markdown Editor — syntax highlighting, line numbers, Edit/View modes, auto-indent, drag-and-drop image support.
  • Wiki-links — [[note-name]] navigation with Ctrl+Click, alias syntax, and automatic new-note creation on broken links.
  • PDF Viewer & Annotations — dual backend (QtPDF / PyMuPDF), non-destructive JSON annotations, reading progress tracking.
  • Papis Literature Bridge — auto-fetch metadata from DOI, arXiv, and ISBN; BibTeX export; tag and collection management.
  • Git Sync — auto-commit, pull, and push; rebase, merge, and stash strategies; visual three-panel conflict resolution dialog.
  • Backlink Graph — interactive force-directed knowledge graph built with NetworkX; orphan detection and graph statistics panel.
  • Global Vault Search — full-text search across all Markdown notes, Papis literature metadata, and PDF annotation content simultaneously.
  • Light / Dark / System Theme — OS-adaptive theming with live preview in Settings and instant cancel-to-revert.
  • Portable Vault Architecture — self-contained folder with TOML configuration; plain text files readable without Noteration.