v1.2.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 v1.2.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 a live HTML preview mode. Write academic notes naturally and switch to rendered view with one keypress.

Ctrl+Shift+V
🧘

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 while writing.

New in v1.1
🕸️

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, arXiv, or ISBN. Export BibTeX per-note or for the entire library in one click.

Papis
🔍

Global Vault Search

One search bar that simultaneously covers all Markdown notes, literature metadata, and PDF annotation content. Supports regular expressions and case-sensitive filters for precise results.

Vault-wide
☁️

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
📖

Academic Writing Guide

Press F2 for an in-app briefing on academic writing strategies — critical reading techniques, citation ethics, argumentation across disciplines, and documentation standards.

New in v1.1
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
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

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

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

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

v1.2.0

2026-05-16
latest
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.