markora 1.0.0

  __  __            _                     
 |  \/  |          | |                    
 | \  / | __ _ _ __| | _____  _ __ __ _   
 | |\/| |/ _` | '__| |/ / _ \| '__/ _` |  
 | |  | | (_| | |  |   < (_) | | | (_| |  
 |_|  |_|\__,_|_|  |_|\_\___/|_|  \__,_|  

💡 Why Markora?

If you love the simplicity, offline-first philosophy, and markdown-native architecture of the popular Android app Markor, Markora brings that exact seamless experience straight into your terminal.

• Zero Cloud Lock-in: Your data is 100% plain Markdown files in ~/Documents (or your custom directory). You own your notes forever.
• Zero Heavy Dependencies: Core CLI and interactive TUI run entirely on the Python 3 standard library. No Electron bloat, no node_modules, no heavy frameworks.
• Dual Personality: Use lightning-fast one-liner CLI commands (markora add, markora qn) for scriptability, or fire up the rich interactive 4-tab Curses TUI (markora ui) for browsing, editing, and task triage.
• Seamless Portability: Sync your folder with Syncthing, Nextcloud, Git, or Android Markor without converting formats.

✨ Key Features

🖥️ Interactive Curses TUI

Launch with markora ui (or alias td ui):

┌────────────────────────────────────────────────────────────────────────┐
│ MARKORA NOTEBOOK | SSOT: TODOLIST.md                                   │
├────────────────────────────────────────────────────────────────────────┤
│ [1] QuickNote   [2] To-Do   [3] Notebook   [4] Search    Filter: (none)│
├──────────────────────────────────┬─────────────────────────────────────┤
│ > [✔] # 1 [P1] Deploy core v1.0  │ Task #1 Details                     │
│   [ ] # 2 [P2] Write user manual │ Section : ACTIVE TASKS              │
│   [ ] # 3 [P3] Refactor keep api │ Status  : DONE                      │
│                                  │ Priority: P1                        │
│                                  │ Scope: Production release           │
│                                  │ Deliverables: Clean package         │
├──────────────────────────────────┴─────────────────────────────────────┤
│ [Space] Toggle [a] Add [r] Edit [d] Del [e] Editor [s] Sync Keep [q]   │
└────────────────────────────────────────────────────────────────────────┘

📦 Installation

Option 1: 1-Line Standalone Installer (Recommended)

curl -fsSL https://raw.githubusercontent.com/zyekhabdul/markora/main/install.sh | bash

This installs markora (and aliases td, todo, mo) into ~/.local/bin/.

Option 2: Pip / Pipx Installation

# Standard install (Zero external dependencies)
pip install git+https://github.com/zyekhabdul/markora.git

# With optional Google Keep synchronization
pip install "markora[keep] @ git+https://github.com/zyekhabdul/markora.git"

Option 3: Manual Clone & Symlink

git clone https://github.com/zyekhabdul/markora.git ~/Projects/markora
cd ~/Projects/markora
make symlink

🚀 CLI Command Reference

All commands support both markora and the ultra-short alias td:

# --- QuickNotes ---
td qn "Remember to review pull request"   # Append thought
td qn                                     # View quicknotes
td qn -e                                  # Edit in $EDITOR

# --- Task Management ---
td add "Ship version 1.0" -p p1           # Add high-priority task
td add "Research new indexing" -s "Inbox" # Add to specific section
td list                                   # List all tasks
td list -p                                # Show only pending tasks
td list -d                                # Show completed tasks
td list -t #backend                       # Filter by tag
td done 1 3                               # Complete tasks #1 and #3
td undone 2                               # Mark task #2 pending
td toggle 1                               # Toggle completion status
td rm 4                                   # Delete task #4

# --- Markdown Notebook ---
td note "System Architecture"             # Create new note in notes/
td note -d                                # Open today's daily note
td notes                                  # List all notebook files
td find "authentication"                  # Search across all notes
td fav list                               # List starred notes
td fav add notes/project.md               # Star a note

# --- TUI & Integrations ---
td ui                                     # Launch interactive 4-tab TUI
td keep auth                              # Connect Google Keep
td keep sync                              # Two-way sync with Keep

⌨️ TUI Keyboard Shortcuts

🔄 Google Keep Bidirectional Sync

Markora includes a built-in sync engine that maps your Google Keep notes to your local markdown hierarchy:

• Daily Notes → Synced with Keep notes labeled daily-notes
• QuickNote → Synced with Keep note titled QuickNote
• General Notes → Synced with Keep notes labeled notes

How to Authenticate:

# Install Keep dependencies
pip install "markora[keep]"

# Run interactive auth (automated browser popup or token paste)
markora keep auth

# Perform two-way sync
markora keep sync

⚙️ Configuration

Markora respects standard Unix configuration paradigms and environment variables:

Config files are stored in ~/.config/markora/ (with automatic fallback to ~/.config/td/).

🐚 Shell Completion

Shell completion scripts for Bash and Zsh are located in completions/:

# Bash
source <(cat completions/markora.bash)

# Zsh
cp completions/markora.zsh ~/.zsh/completion/_markora

🛠️ Development & Testing

git clone https://github.com/zyekhabdul/markora.git
cd markora

# Setup editable install with test dependencies
make dev

# Run comprehensive test suite
make test

# Lint & syntax validation
make lint

📄 License

MIT License © 2026 zyekhabdul. Built with craftsmanship for sovereign terminal enthusiasts.