NoteDown 📝

A powerful Git-backed knowledge management system with CLI and VSCode integration.

Overview

NoteDown is a comprehensive note-taking and knowledge management system that combines the power of Git version control with the convenience of modern editing tools. It features a robust command-line interface written in Go and a rich VSCode extension for GUI users.

🆕 Latest Features (v3.14.15): Desktop GTK application, improved search functionality, enhanced CLI installation, cross-platform build system, and comprehensive documentation!

📚 Documentation

• CLI Usage Guide - Complete command reference and examples
• VSCode Extension Guide - Extension features and usage
• Configuration Guide - Setup and customization options
• Installation Guide - Step-by-step installation instructions
• Quick Start Guide - Get up and running in minutes
• Changelog - Release notes and version history

Features

🚀 Command-Line Interface

• 📁 Repository Management: Initialize, sync, and manage note repositories
• ✏️ Note Authoring: Create and edit notes with YAML frontmatter
• 🏷️ Content Organization: Hierarchical listing and tagging system
• ⚡ Quick Snippets: Instant note capture with noted "quick thought"
• 🔧 Automatic Setup: One-command dependency installation
• 📁 Asset Management: Organized media files with automatic indexing
• 🔄 Version Control: Full Git integration with automatic commits
• 📄 Export Capabilities: PDF export via Pandoc
• 🔌 VSCode Integration: Built-in command to package the extension

🎨 VSCode Extension

• ✨ WYSIWYG Editor: Live markdown editing with real-time preview
• 🌲 Notes Explorer: Tree view with metadata display
• 📊 Interactive Dashboard: Repository statistics and quick actions
• 🎯 Slash Commands: Quick formatting with / shortcuts
• ⌨️ Keyboard Navigation: Full keyboard support for menus and commands
• 🔗 Seamless Integration: Direct CLI command execution from GUI

🚀 Quick Installation

Option 1: Automatic Setup (Recommended)

# Clone and build
git clone <repository-url>
cd NoteDown
go build -o noted ./cmd/noted

# Install dependencies and noted executable automatically
./noted setup

# That's it! noted is now available globally
noted --version

Option 2: Manual Setup

# Install dependencies first
# On Ubuntu/Debian: sudo apt install git pandoc nodejs npm
# On Fedora: sudo dnf install git pandoc nodejs npm
# On macOS: brew install git pandoc node

# Then build NoteDown
go build -o noted ./cmd/noted
npm install -g vsce

📖 For detailed installation instructions, see Installation Guide

⚡ Quick Start

# 1. Initialize your first repository
mkdir my-notes && cd my-notes
noted init --remote=git@github.com:username/my-notes.git
# Will ask if you want to set this as your default repository

# 2. Create your first note
noted new "My First Note"

# 3. Add a quick snippet from anywhere
noted snippet "This is a quick thought I want to capture"

# 4. List and organize your notes
noted list --format=tree

# 5. Save and sync everything
noted save -m "My first notes"
noted sync

🎯 For a complete walkthrough, see Quick Start Guide

📋 Command Reference

🆕 Quick Actions

• noted "text" - Add quick snippet to default repository
• noted setup - Install all dependencies and noted executable automatically
• noted set default <path> - Set default repository for snippets

📁 Repository Management

• noted init [directory] - Initialize a new noted repository
• noted rescan - Rebuild note and asset indexes
• noted sync - Synchronize with remote Git repository

✏️ Note Operations

• noted new "Title" - Create a new note
• noted edit "search-term" - Edit an existing note
• noted list [--format=tree|json] - List notes with metadata
• noted snippet "text" - Add timestamped snippet

💾 Content Management

• noted save [-m "message"] - Save and commit all changes
• noted export note.md --pdf - Export note to PDF

🔧 Development

• noted vsix - Build and package the VSCode extension

📖 For complete command documentation, see CLI Usage Guide

🎨 VSCode Extension

⚡ Quick Install

# Build and install the extension
noted vsix
# Then install the generated .vsix file in VSCode

✨ Key Features

• 🔥 WYSIWYG Editor: Live markdown editing with instant preview
• ⚡ Slash Commands: Type / for quick formatting options
• 🌲 Smart Explorer: Browse notes with rich metadata
• 📊 Live Dashboard: Real-time statistics and insights
• ⌨️ Keyboard Navigation: Full keyboard support
• 📱 Asset Management: Drag-and-drop media files

📖 For detailed extension documentation, see VSCode Extension Guide

🖥️ NoteDown GTK Desktop Application

⚡ Beautiful Linux Desktop Experience

NoteDownGTK brings the power of NoteDown to your Linux desktop with a native GTK4 application designed for productivity and elegance.

# Quick installation on Linux
cd NoteDownGTK
make install

✨ Key Features

• 🎨 Modern Interface: Native GTK4 design with dark/light theme support
• 📝 Rich Markdown Editor: Syntax highlighting with live preview
• 🗂️ File Navigator: Browse and organize your notes with ease
• 🔧 Integrated Tools: Dashboard, outline view, and search functionality
• ⚡ CLI Integration: Direct integration with the noted CLI engine
• 🖱️ Sticky Mode: Always-on-top window for quick note access
• 🔍 Full-Text Search: Powerful search across all your notes
• 📊 Dashboard View: Visual insights into your knowledge base

📦 Installation Options

📋 System Requirements:

• Linux (GTK4 support required)
• Python 3.11+
• PyGObject 3.42+

🚀 Quick Install (Recommended):

# Navigate to NoteDownGTK directory
cd NoteDownGTK

# Install with desktop integration
make install

# Or install for current user only
make install-user

🐳 Distribution Packages:

# Create distribution packages
make dist          # All formats
make dist-deb      # Debian/Ubuntu
make dist-rpm      # Fedora/CentOS
make dist-flatpak  # Flatpak
make dist-appimage # AppImage

🛠️ Development Setup:

# Set up development environment
make setup-dev

# Run from source
make dev

🎯 Usage

Launch Methods:

1. Desktop Integration: Launch from your application menu or desktop
2. Command Line: Run notedowngtk from terminal
3. Sticky Mode: Quick access with notedowngtk --sticky

Interface Overview:

• Left Panel: File navigator and note tree
• Center Panel: Markdown editor with syntax highlighting
• Right Panel: Tools (dashboard, outline, search, etc.)
• Status Bar: Repository status and quick actions

🔧 Configuration

NoteDownGTK automatically integrates with your noted CLI configuration and repositories.

Desktop Integration:

• Application launcher entry
• MIME type associations for .md files
• System theme integration
• Notification support

📖 For detailed desktop application documentation, see NoteDownGTK README

Configuration

Global Config (~/.config/noted/config.yaml)

default_editor: "code"
git:
  user_name: "Your Name"
  user_email: "your.email@example.com"
templates:
  basic:
    tags: []
    category: "notes"

Local Config (.noted)

version: "1.0"
git:
  remote_url: "git@github.com:user/notes.git"
  auto_sync: true
index:
  scan_patterns: ["*.md", "*.txt"]
export:
  pandoc:
    output_dir: "exports"

Note Format

Notes use Markdown with YAML frontmatter:

---
title: "Note Title"
tags: ["development", "golang"]
category: "programming"
created_at: 2025-08-28T14:30:00-06:00
updated_at: 2025-08-28T15:45:00-06:00
---

# Note Content

Your markdown content goes here with full GitHub Flavored Markdown support.

Architecture

NoteDown/
├── cmd/noted/           # CLI application entry point
├── internal/            # Core Go packages
│   ├── config/         # Configuration management
│   ├── git/           # Git operations wrapper
│   ├── index/         # Note indexing system
│   ├── note/          # Note parsing and management
│   └── tree/          # Hierarchical listing
├── vscode-extension/   # VSCode extension
│   ├── src/           # TypeScript source
│   ├── media/         # CSS/JS assets
│   └── out/           # Compiled JavaScript
└── test/              # Test files

Development

🔨 Build System

NoteDown features a comprehensive Makefile-based build system that supports cross-platform compilation and automated releases:

# Quick build for current platform
make build

# Build for all platforms and create releases
make release

# Build with checksums for distribution
make checksums

# Development build with race detection
make dev

# Run tests and linting
make test
make lint

📋 Supported Platforms:

• Linux (amd64, arm64, 386)
• macOS (amd64, arm64)
• Windows (amd64, arm64, 386)
• FreeBSD (amd64)
• OpenBSD (amd64)

📖 For complete build system documentation, see Build System Guide

🧪 Testing

# Run all tests
make test

# Run Go tests only
go test ./...

# Run VSCode extension tests
cd vscode-extension && npm test

# Test the built binary
make test-build

🛠️ Development Workflow

# Set up development environment
make setup

# Build and test
make dev
make test

# Format and lint
make fmt
make lint

# Build release
make build

Contributing

1. Fork the repository
2. Create a feature branch
3. Make your changes
4. Add tests for new functionality
5. Ensure all tests pass
6. Submit a pull request

License

MIT License - see LICENSE for details.

Support

For issues and feature requests, please visit the GitHub repository.

---

NoteDown - Where knowledge meets version control 🚀