✨ Totion - Terminal Note-Taking TUI

A powerful, fast, and lightweight note-taking application for your terminal, built with Go and Bubble Tea.

🎯 Problem Statement

Modern note-taking apps are often bloated, slow, cloud-dependent, and distract with fancy features. Developers and power users need a fast, keyboard-driven, offline-first solution that works seamlessly in the terminal where they already spend most of their time.

Totion solves this by providing:

• ⚡ Lightning-fast terminal interface with zero startup time
• ⌨️ 100% keyboard-driven workflow - no mouse needed
• 📝 Markdown & Plain Text support - your notes, your way
• 🌐 Multi-language UI - Work in your native language with AI-powered translation
• 🔒 Privacy-first - All notes stored locally, you own your data
• 📁 Zero lock-in - Standard markdown files, use any editor
• 🎨 Distraction-free - Clean, minimal interface that stays out of your way

🚀 Features

Core Features ✅ (Fully Working)

• Multi-Format Support: Create notes in Markdown (.md) or Plain Text (.txt)
• File Management: Create, read, update, and delete notes with confirmation
• Advanced Search: Full-text search across all notes with tag search support (#tagname)
• Keyboard-Driven: Full keyboard navigation and shortcuts
• Clean TUI: Simple and intuitive terminal user interface with 2-3 colors
• Templates: 7 Quick note templates (Meeting, Todo, Journal, Project, Code, Book, Blank)
• Themes: 6 Color schemes available (Default Blue, Dark, Light, Monokai, Solarized, Nord)
• Help System: Comprehensive help with menu-based navigation (select topics 1-9)
• Advanced Export: Export notes to HTML, PDF, JSON, Plain Text, or Markdown - with batch export
• Enhanced Import: Import from Notion, Obsidian, JSON, CSV, or batch import entire directories
• Statistics: View word count, reading time, and vault statistics
• Git Integration: Initialize repo, commit changes, view history and status
• Sync & Backup: Full vault backup/restore with cloud sync support
• Smart Notebooks: Organize notes in folders with search, tags, export, and statistics per notebook
• Wiki Linking: Connect notes with [[Note Title]] syntax (Ctrl+K in editor)
• Auto-Save: Automatically saves notes every 30 seconds while editing
• Recently Opened: Quick access to your last 10 opened notes
• Custom Templates: Save your own note templates for reuse
• Smart Tags: Quick access to all #hashtags with T key - search by tags in full search
• Multi-Language UI: Change interface language to 37 languages with real-time AI translation powered by Lingo.dev - includes Spanish, French, German, Japanese, Chinese, Korean, Portuguese, Italian, Russian, Arabic, Hindi, Dutch, Polish, Turkish, Swedish, Norwegian, Danish, Finnish, Greek, Czech, Romanian, Hungarian, Vietnamese, Thai, Indonesian, Hebrew, Ukrainian, Bulgarian, Croatian, Slovak, Slovenian, Lithuanian, Latvian, Estonian, Malay, and Filipino

Available Templates (Ctrl+T)

1. 📋 Meeting Notes - Structured meeting documentation
2. ✅ Todo List - Checkbox-based task list
3. � Journal Entry - Daily journal template
4. � Project Plan - Project planning structure
5. � Code Snippet - Code documentation template
6. 📚 Book Notes - Book reading notes
7. 📄 Blank - Empty template

Available Themes (P key from home)

1. � Default (Blue) - Clean blue color scheme
2. Dark - Dark theme for night coding
3. ☀️ Light - Light theme for daytime
4. 🎭 Monokai - Popular Monokai colors
5. 🌊 Solarized Dark - Solarized dark palette
6. ❄️ Nord - Nord color scheme

�️ Interface

Here's what Totion looks like in action:

Home Screen

The main hub with pinned notes, quick start guide, and all available features.

Notes List

Browse all your notes with easy navigation and search filtering.

Editor

Clean, distraction-free writing environment with auto-save and markdown support.

Language Menu

Translations

Help Menu

Comprehensive help system with organized topics and easy navigation.

�📦 Installation

Prerequisites

• Go 1.21 or higher
• Git (optional, for version control features)
• wkhtmltopdf (required for PDF export)
• Lingo.dev API key (optional, for UI translation feature)

go install github.com/0xshariq/totion

cd totion

make run

Install wkhtmltopdf

Ubuntu/Debian:

sudo apt-get install wkhtmltopdf

macOS:

brew install wkhtmltopdf

Windows: Download and install from: https://wkhtmltopdf.org/downloads.html

Build from Source

# Clone the repository
git clone https://github.com/0xshariq/totion.git
cd totion

# Build the application
make build

# Run the application
make run

# Or install globally
make install

# Clean build artifacts
make clean

🎮 Usage & Keyboard Shortcuts

Quick Start

1. Launch Totion: Run ./totion or make run
2. Create a note: Press Ctrl+N, enter name, select format (Tab), press Enter
3. Type your note: Start typing immediately
4. Save: Press Ctrl+S to save and return home
5. View notes: Press Ctrl+L to see all notes
6. Get help: Press Ctrl+H or ? anytime

Complete Keyboard Reference

Complete Keyboard Reference

🏠 Home Screen Shortcuts

Shortcut	Action
Ctrl+N	Create new note with custom name
Ctrl+D	Create daily journal note (auto-dated)
Ctrl+Q	Open quick scratch pad
Ctrl+L	List all notes
Ctrl+H or ?	Show help menu (navigate with numbers, scroll with ↑↓)
Ctrl+T	Open templates menu
P	Open themes menu
T	View tags browser (all #hashtags in notes)
Alt+E	Export note (HTML, PDF, JSON, Markdown, Text)
Alt+I	Import notes (Notion, Obsidian, JSON, CSV)
S	View statistics dashboard
G	Git operations menu
Alt+Y	Sync & backup menu
B	Notebooks/folders manager (with search & export)
Alt+P	Pin/unpin note
/	Search notes
Alt+T	Change UI language (translate interface)
Q	Quit application

📋 List View Shortcuts

Shortcut	Action
↑ / ↓	Navigate notes up/down
Enter	Open selected note for editing
Ctrl+D	Delete selected note (with confirmation)
/	Start search/filter
Esc	Clear filter or return to home

✏️ Editor Mode Shortcuts

Shortcut	Action
Ctrl+S	Save note and close editor
Alt+F	Toggle focus mode (distraction-free)
Alt+P	Pin/unpin current note
Alt+L	Show wiki linking help
Esc	Discard changes and close editor
Type normally	Edit note content

🌐 Change Language (Press Alt+T)

Want to use Totion in your native language? We've got you covered!

How to Change Language:

Key	What it does
Alt+T	Open the language menu
↑ ↓	Move up/down through language options
PgUp PgDn	Scroll faster through languages
Enter	Select your language
Esc	Cancel and go back

Available Languages (37 total):

• ES Spanish (Español) - FR French (Français) - DE German (Deutsch)
• IT Italian (Italiano) - PT Portuguese (Português) - JP Japanese (日本語)
• KR Korean (한국어) - CN Chinese (中文) - RU Russian (Русский)
• SA Arabic (العربية) - IN Hindi (हिन्दी) - NL Dutch (Nederlands)
• PL Polish (Polski) - TR Turkish (Türkçe) - SE Swedish (Svenska)
• NO Norwegian (Norsk) - DK Danish (Dansk) - FI Finnish (Suomi)
• GR Greek (Ελληνικά) - CZ Czech (Čeština) - RO Romanian (Română)
• HU Hungarian (Magyar) - VN Vietnamese (Tiếng Việt) - TH Thai (ไทย)
• ID Indonesian (Bahasa Indonesia) - IL Hebrew (עברית) - UA Ukrainian (Українська)
• ES_MX Spanish Latin America - BG Bulgarian (Български) - HR Croatian (Hrvatski)
• SK Slovak (Slovenčina) - SI Slovenian (Slovenščina) - LT Lithuanian (Lietuvių)
• LV Latvian (Latviešu) - EE Estonian (Eesti) - MY Malay (Bahasa Melayu)
• PH Filipino (Tagalog)

What Gets Translated:

✅ All menus and buttons
✅ Help text and instructions
✅ Keyboard shortcut descriptions
✅ Status messages and notifications

❌ Your note content (stays in your language)
❌ File names and folders
❌ Error technical details

---

🚀 Setup Translation (Optional)

1. Get free API key from lingo.dev
2. Create .env file in totion folder
3. Add: LINGODOTDEV_API_KEY=your_key_here
4. Press Alt+T and pick your language from 37 options

No API key? App works in English by default.

Note: Translation service runs silently in the background - no terminal logs or noise!

---

🔍 Advanced Search Features

Totion provides powerful search capabilities to help you find notes quickly.

Full-Text Search (Ctrl+/ from anywhere):

Search for any text across all your notes instantly. The search looks through:

• Note content (line by line)
• All markdown and text files in your vault
• Shows line numbers and snippets for context

Tag Search:

Search specifically for notes containing tags:

• Type #tagname in the search to find all notes with that tag
• Example: #work finds all notes tagged with #work
• Example: #meeting finds meeting notes
• Case-insensitive matching

Quick Filter (/ key in list view):

Fast filtering of notes in the list view by filename or content.

Tag Browser (T key):

View all tags in your vault organized by frequency. Click any tag to see all notes containing it.

Search Tips:

• Regular text search: Just type your query
• Tag search: Prefix with # (e.g., #project)
• Combine with notebooks: Search within specific folders
• Results show up to 100 matches with context snippets

---

💡 How Translation Works

When you pick a language, Totion uses AI to translate the interface. It's smart enough to understand buttons, menus, and shortcuts.

First Time: Takes 2-3 seconds to load translations After That: Instant! Everything is cached

What Gets Translated:

• Menus and buttons
• Help text and instructions
• Keyboard shortcuts
• Status messages

What Stays the Same:

• Your note content
• File names
• Error messages

---

🔧 Translation Issues?

"I see mixed languages"
👉 Wait 2-3 seconds - translations are loading with quality mode (95%+ accuracy).

"Seems slow"
👉 Only first time. Then it's instant! Over 100 strings are pre-cached.

"Some text not translating"
👉 Error messages and keyboard shortcuts stay in English. That's normal.

"Terminal shows logs/spam"
👉 Not anymore! Translation service runs completely silently in background.

"Can't see all languages"
👉 Use arrow keys or Page Up/Down to scroll through all 37 languages!

---

🎯 Translation Features

• 🌍 37 Languages: Spanish, French, German, Japanese, Chinese, Korean, Portuguese, Italian, Russian, Arabic, Hindi, Dutch, Polish, Turkish, Swedish, Norwegian, Danish, Finnish, Greek, Czech, Romanian, Hungarian, Vietnamese, Thai, Indonesian, Hebrew, Ukrainian, Bulgarian, Croatian, Slovak, Slovenian, Lithuanian, Latvian, Estonian, Malay, Filipino
• 🎯 95%+ Accuracy: Smart context detection with quality mode enabled
• ⚡ Fast & Smooth: Instant after first load with intelligent caching
• 🔇 Silent Operation: No terminal spam - runs quietly in background
• 📜 Scrollable Menu: Viewport scrolling for easy navigation through all languages
• 🎨 UI Only: Your notes stay in your language

Requirements: Node.js + Free API key from lingo.dev

Note: Works in English without API key.

📤 Export Menu (Press Alt+E from home)

Key	Format
1	Export to HTML (beautiful web page)
2	Export to PDF (requires wkhtmltopdf)
3	Export to Markdown (preserve formatting)
Esc	Cancel export

📥 Import Menu (Press Ctrl+I from home)

Key	Source
1	Import from Notion (JSON export)
2	Import from Markdown files
3	Import plain text files
Esc	Cancel import

🔄 Git Menu (Press G from home)

Key	Action
1	Initialize Git repository
2	Commit all changes
3	View commit history
4	View Git status
Esc	Cancel

☁️ Sync & Backup Menu (Press Ctrl+Y from home)

Key	Action
1	Backup vault to ZIP
2	Restore from backup
3	Sync to cloud (if configured)
4	Sync from cloud
Esc	Cancel

📝 Templates Menu (Press Ctrl+T)

Key	Template
1	Meeting Notes - Structured meeting documentation
2	Todo List - Checkbox-based task list
3	Journal Entry - Daily journal template
4	Project Plan - Project planning structure
5	Code Snippet - Code documentation template
6	Book Notes - Book reading notes & highlights
7	Blank Note - Start from scratch
Esc	Cancel

🎨 Themes Menu (Press P from home)

Key	Theme
1	Default (Blue) - Fresh and modern
2	Dark - Easy on the eyes
3	Light - High contrast
4	Monokai - Popular developer theme
5	Solarized Dark - Classic color scheme
6	Nord - Cool, bluish theme
Esc	Cancel

📂 Notebooks Menu (Press B from home)

Key	Action
1	Create new notebook
2	List all notebooks
3	Rename notebook
4	Delete notebook
5	Move note to notebook
6	View notebook contents
Esc	Cancel

❓ Help & Documentation (Press Ctrl+H or ?)

In the help menu, press the corresponding number to view a topic:

Key	Topic
1	Keyboard Shortcuts - Complete key reference
2	Getting Started - Beginner's guide
3	Templates Guide - Using note templates
4	Themes Guide - Customizing appearance
5	Export & Import - Moving notes in/out
6	Git Integration - Version control
7	Statistics - Analytics dashboard
8	Sync & Backup - Cloud sync setup
9	Notebooks - Organization system
0	Developer Integration - API documentation
Esc	Return to previous menu or home

Navigation in Help:

• Use ↑↓ arrow keys or mouse scroll to navigate content
• Press Esc to go back to the previous menu
• All help sections now support scrolling!

🎮 Quick Start Guide

First Time Setup

1. Launch the app:

   cd totion
   make run

2. Create your first note:

   • Press Ctrl+N
   • Type a name (e.g., "My First Note")
   • Press Enter
   • Press Tab to switch between Markdown/Text format
   • Press Enter again to create

3. Start writing:

   • Type your content in the editor
   • Press Ctrl+S to save and close

4. View your notes:

   • Press Ctrl+L to see all notes
   • Use arrow keys to navigate
   • Press Enter to open a note

5. Get help anytime:

   • Press Ctrl+H or ?
   • Select a topic by pressing 1-9
   • Read the specific help for that feature
   • Press Esc to go back to menu or home

Common Workflows

Creating Notes with Templates

1. Press Ctrl+T from home screen
2. Select a template (1-7)
3. Enter a note name
4. The template content will be loaded automatically
5. Edit and save with Ctrl+S

Deleting Notes

1. Press Ctrl+L to open notes list
2. Use arrow keys to navigate to the note
3. Press Ctrl+D to request deletion
4. Press Y to confirm or N to cancel

Using Wiki-Style Links

• In the editor, type [[Note Name]] to link to another note
• Press Ctrl+K to see linking help
• Links are detected automatically when editing

Importing from Other Apps

1. Press I from home screen
2. Select import source:
   • 1 for Notion (JSON export)
   • 2 for Obsidian vault
   • 3 for plain text files (.md/.txt from Git repos)
3. Follow the prompts

Version Control with Git

1. Press G from home screen
2. Initialize repository (first time): Press 1
3. Commit changes: Press 2
4. View history: Press 3
5. Check status: Press 4

Exporting Notes

1. Open a note in the editor
2. Press E from home screen
3. Select format: 1 HTML, 2 Plain Text, 3 Markdown
4. File will be exported to /tmp/

📁 File Structure & Storage

Storage Location

Notes are stored in: ~/.totion/

~/.totion/
├── note1.md              # Markdown notes
├── note2.txt             # Plain text notes
├── project-notes.md      # More notes
└── meeting-notes.md      # Template-based notes

File Formats

• Markdown files: .md extension - Full markdown support
• Plain text files: .txt extension - Simple text notes
• All files are human-readable plain text
• Easy to backup, sync, and version control
• Compatible with other markdown editors

Backup Your Notes

Your notes are just files! You can:

• Copy ~/.totion/ folder to backup
• Use Git for version control (press G in app)
• Sync with cloud storage (press Ctrl+Y in app)
• Export individual notes to HTML/PDF (press E in app)

🛠️ Troubleshooting

Application won't start

# Rebuild clean
make clean
make build

Can't scroll in help screen

• Help is now menu-based - no scrolling needed!
• Press Ctrl+H to open help menu
• Select a topic (1-9) to see specific help
• Press Esc to go back to menu or home

Can't type in editor

• Make sure you're in editor mode (file is open)
• Press Esc to exit any active filter/search
• Check that another app isn't capturing keyboard

Notes not appearing in list

• Check ~/.totion/ directory exists
• Verify file extensions (.md or .txt)
• Press Ctrl+L to refresh list

Export/Import not working

• Make sure you have a note open for export
• Check file paths for import sources
• Verify permissions on the target directories

📚 Tips & Best Practices

1. Use Templates: Press Ctrl+T for quick structured notes
2. Keyboard First: Learn shortcuts for fastest workflow
3. Regular Backups: Use Git (G) or Sync (Ctrl+Y) for backups
4. Wiki Links: Use [[Note Name]] to link related notes
5. Search Often: Use / in list view for quick filtering
6. Simple Styling: The app uses 2-3 colors for clean, readable interface
7. Plain Text: Notes are just files - easy to backup and portable

🗺️ Roadmap

Current Status ✅

• Core note-taking (Create, Read, Update, Delete)
• Multi-format support (Markdown & Plain Text)
• Search and filtering with /
• Templates system (7 templates)
• Themes system (6 themes)
• Help system with menu-based navigation (no scrolling issues)
• Export to HTML/Plain/Markdown
• Import from Notion/Obsidian/Git
• Statistics tracking
• Git integration
• Sync & backup
• Notebooks/folders
• Wiki-style linking
• Simplified styling (2-3 colors)
• Auto-save functionality

Coming Soon 🚀

• Split view mode
• Better scrolling in all views
• Customizable key bindings
• Status bar with live stats
• Focus mode (distraction-free writing)
• Tag system for notes
• Full-text search across all notes

Potential Real-World Features 💡

These features would make Totion more practical for everyday use:

Productivity Features

• Daily Journal Automation - Auto-create daily notes with date-based templates
• Task Management - Parse - [ ] checkboxes, track completion, show pending tasks
• Meeting Minutes - Quick capture meeting notes with attendees, agenda, action items
• Quick Capture - Rapid note entry mode (Ctrl+Q) for fleeting thoughts
• Note Templates Library - Expandable template system with custom user templates
• Scheduled Notes - Set reminders or schedules for notes (deadlines, follow-ups)

Organization Features

• Tag System - Add #tags to notes, filter by tags, tag cloud view
• Favorites/Pins - Pin important notes to the top of the list
• Recently Opened - Quick access to last 5-10 edited notes
• Note Relationships - Bidirectional links showing "what links here"
• Archive System - Archive old notes without deleting them
• Note Categories - Auto-categorize notes (work, personal, ideas, etc.)

Collaboration Features

• Share Notes - Export shareable links or QR codes for notes
• Markdown Preview - Live preview mode for markdown notes (Ctrl+M)
• PDF Export - Export notes to PDF with custom formatting
• Presentation Mode - Present notes full-screen with minimal UI
• Note Comments - Add inline comments/annotations without editing content

Advanced Writing Features

• Word Count Goals - Set daily writing goals, track progress
• Writing Streaks - Track consecutive days of writing
• Spell Check - Basic spell checking for text content
• Auto-Complete - Suggest completions based on note history
• Snippets - Quick insertion of frequently used text blocks
• Markdown Shortcuts - Quick formatting (Ctrl+B for bold, etc.)

Search & Discovery

• Full-Text Search - Search content across all notes (not just titles)
• Fuzzy Search - Find notes even with typos
• Search History - Remember recent searches
• Smart Suggestions - Suggest related notes based on content
• Filter Combinations - Filter by date + tag + type + folder

Integration Features

• Browser Extension - Save web clips to Totion
• Mobile Companion App - View/edit notes on mobile (read-only mode)
• API Server - REST API for external integrations
• Webhook Support - Trigger actions when notes are created/updated
• Email Integration - Email notes to yourself (to specific email address)
• CLI Mode - Command-line interface for scripting (totion create "note name")

Smart Features

• Auto-Tagging - Suggest tags based on note content
• Smart Links - Auto-detect and highlight URLs, file paths, dates
• Note Templates from Usage - Learn from your writing patterns
• Duplicate Detection - Warn when creating similar notes
• Broken Link Detection - Find and fix broken wiki-style links

Performance & Reliability

• Lazy Loading - Load notes on demand for large vaults (1000+ notes)
• Index Search - Build search index for instant results
• Auto-Backup - Automatic daily backups with rotation
• Conflict Resolution - Handle sync conflicts gracefully
• Undo/Redo - Multi-level undo for edits (Ctrl+Z, Ctrl+Y)

Developer Features

• Lua Plugins - Scriptable plugins using Lua
• Custom Themes - Full theme customization (JSON-based)
• Debug Mode - Show performance metrics and logs
• Export API - Programmatic access to export functions
• Webhooks - Trigger external actions on events

Most Requested Features (Priority)

Based on typical note-taking app usage, these would have the most impact:

1. ⭐ Full-text search - Search within note content, not just names
2. ⭐ Tag system - Organize and filter notes with tags
3. ⭐ Task checkboxes - Parse and manage - [ ] todo items
4. ⭐ Markdown preview - See formatted output while writing
5. ⭐ Daily notes - Auto-create today's journal entry
6. ⭐ Mobile view - Sync and view on mobile devices

🤝 Contributing

Contributions are welcome! The codebase is well-structured and modular. Refer CONTRIBUTING.md

Project Structure

totion/
├── cmd/totion/              # Entry point (main.go)
├── internal/
│   ├── app/                 # Main application logic
│   │   ├── app.go          # Core Model, Init, Update
│   │   ├── handlers.go     # All handler functions
│   │   └── views.go        # View rendering
│   ├── models/             # Data models (Note, FileFormat)
│   ├── storage/            # File operations (CRUD)
│   ├── ui/
│   │   ├── components/     # Reusable UI components
│   │   ├── help/           # Help content
│   │   └── styles/         # Simple color styling (2-3 colors)
│   ├── features/           # Advanced features
│   │   ├── export/         # Export to HTML/Plain/Markdown
│   │   ├── import/         # Import from Notion/Obsidian
│   │   ├── git/            # Git version control
│   │   ├── sync/           # Backup and sync
│   │   ├── stats/          # Statistics tracking
│   │   ├── linking/        # Wiki-style links
│   │   └── templates/      # Note templates
│   ├── notebook/           # Folder/notebook management
│   └── themes/             # Theme system
├── go.mod                  # Dependencies
├── makefile                # Build commands
└── README.md               # This file

Code Organization

The codebase follows clean architecture principles:

• Separation of Concerns: app.go (core), handlers.go (logic), views.go (UI)
• Feature Modules: Each feature is self-contained in internal/features/
• Reusable Components: UI components in internal/ui/components/
• Simple Styling: Using lipgloss with 2-3 colors for readability

Making Changes

1. Fork the repository
2. Create a feature branch
3. Make your changes
4. Test with make run
5. Build with make build
6. Submit a pull request

📄 License

This project is licensed under the MIT License.

See the LICENSE file.

👤 Author

Sharique - @0xshariq

• GitHub: 0xshariq
• Project: totion

🙏 Acknowledgments

Built with these amazing libraries:

• Bubble Tea - The Go TUI framework powering the interface
• Bubbles - Ready-to-use TUI components (textarea, textinput, list)
• Lip Gloss - Terminal styling and colors
• Lingo.dev - AI-powered translation service

Special thanks to the Charm community for creating excellent terminal tools and Lingo.dev for making multi-language support possible!

🌟 Star History

If you find Totion useful, please consider giving it a star on GitHub!

---

Made with ❤️ and Go by Sharique

Happy note-taking! 📝