Settings & Configuration

⚙️ Settings & Configuration Guide

Complete guide to customizing NaviDuck to work exactly how you want. From search engines to themes to advanced preferences.

📋 Table of Contents

Quick Settings Overview
Search Engine Configuration
UI & Display Settings
Privacy & Security Settings
Performance Settings
Data Management Settings
Advanced Configuration
Troubleshooting
Pro Tips

🎯 Quick Settings Overview

Accessing Settings

# Main command
settings

# Quick access from anywhere
# Just type: settings

Settings Menu Structure

⚙️ Settings
┌─ 1. Change default search engine
├─ 2. Manage search engines
├─ 3. Toggle icons (Emoji/Nerd Font)
├─ 4. Set Tor path manually
├─ 5. Clear history
├─ 6. Clear bookmarks
├─ 7. Theme settings
├─ 8. Performance settings
├─ 9. Privacy settings
├─ 10. Reset all settings
└─ 11. Back to main

Quick Configuration Examples

Basic Setup (Recommended)

settings
# 1. Set default engine: Brave
# 3. Choose icon style: Your preference
# Done!

Privacy-Focused Setup

settings
# 1. Set default engine: DuckDuckGo
# 3. Icons: Emoji (more universal)
# 9. Privacy: Enable all options

Developer Setup

settings
# 1. Set default engine: Google (for docs)
# 3. Icons: Nerd Font (looks better in terminals)
# 8. Performance: Enable debugging

🔧 Search Engine Configuration

Default Search Engine

Change Default Engine

settings
# Choose option 1
# Select from list of enabled engines

Current Supported Engines

1. 🦆 DuckDuckGo (HTML) - ddg
2. 🦆 DuckDuckGo API - ddg_api  
3. 🏮 Google - google
4. 📚 Wikipedia - wikipedia
5. 🦁 Brave Search - brave

Engine Comparison

Engine	Speed	Privacy	CAPTCHA	Best For
Brave	Fast	Good	Rare	Default, general use
DuckDuckGo	Medium	Excellent	Rare	Privacy focus
Google	Fast	Poor	Frequent	Comprehensive results
Wikipedia	Fast	Good	Never	Academic/research
DDG API	Fast	Excellent	Never	Quick answers

Search Engine Management

Enable/Disable Engines

settings
# Choose option 2 (Manage search engines)
# Then: enable 1, disable 2, etc.

Engine Priority Order

# NaviDuck automatically chooses:
# 1. User-specified engine (search google query)
# 2. Default engine (s query)
# 3. Fallback if CAPTCHA detected

Custom Engine Configuration

(Advanced - edit config file)

{
  "engines": {
    "myengine": {
      "name": "My Custom Engine",
      "url": "https://mysearch.com/search",
      "params": {"q": "{query}"},
      "enabled": true
    }
  }
}

Search Preferences

Results Per Page

# Currently fixed at 10 results
# Future: settings -> Results: 10/20/50

Auto-Switch on CAPTCHA

# Enabled by default
# When CAPTCHA detected, switches to next available engine
# Can't be disabled currently

Search Timeout

# Default: 10 seconds
# Future: settings -> Search timeout: 5/10/30 seconds

🎨 UI & Display Settings

Icon Themes

Toggle Between Icon Sets

settings
# Choose option 3
# Toggle between Emoji and Nerd Font icons

Icon Set Comparison

Nerd Font Icons: 󰇯 󰍉 󰋜 󰁍 󰁔 󰔄
Emoji Icons: 🌐 🔍 🏠 ⬅ ➡ 🔄

Nerd Font looks better in compatible terminals
Emoji works everywhere but less precise

Terminal Requirements

For Nerd Fonts:

# Install a Nerd Font
# Configure terminal to use it
# Popular: CaskaydiaCove NF, FiraCode NF, JetBrainsMono NF

For Emoji:

# Works on most modern terminals
# May look different across platforms

Color Themes

Available Themes

settings
# Choose option 7 (Theme settings)

Theme Options:

Dark (Default) - Dark background, light text
Light - Light background, dark text
Auto - Follows system theme
High Contrast - Better visibility
Custom - Manual color configuration

Theme Examples

Dark Theme:

┏━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━┓
┃        NaviDuck Browser             ┃
┗━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━┛
🔍 Search: python tutorial

Light Theme:

┏━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━┓
┃        NaviDuck Browser             ┃
┗━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━┛
🔍 Search: python tutorial

Display Preferences

Page Display Settings

# Character limit per page
# Default: 2000 characters
# Future: settings -> Page limit: 1000/2000/5000

Result Display Format

# Compact vs Detailed view
# Future: settings -> Result style: Compact/Detailed

Animation Effects

# Loading animations
# Future: settings -> Animations: On/Off

Layout Customization

Header Customization

# Show/hide elements in header
# Future: settings -> Header: Full/Minimal/Custom

Prompt Style

# Change command prompt
# Future: settings -> Prompt: Default/Simple/Custom

Information Density

# How much info to show
# Future: settings -> Verbosity: Minimal/Normal/Detailed

🔒 Privacy & Security Settings

Privacy Controls

History Settings

settings
# Choose option 5 (Clear history)
# Or configure retention:

History Options:

Store all history (default)
Store only searches
Store only visits
Don't store history

Data Retention

# Auto-clear after X days
# Future: settings -> Keep history: 7/30/90 days/Forever

Anonymous Mode

# Don't store anything this session
# Future: naviduck.py --private

Security Settings

Connection Security

# Force HTTPS where possible
# Future: settings -> Always use HTTPS: On/Off

Warning Levels

# Security warnings
# Future: settings -> Warnings: All/Important/None

Safe Browsing

# Warn about suspicious sites
# Future: settings -> Safe browsing: On/Off

Tor Configuration

Tor Path Setting

settings
# Choose option 4 (Set Tor path manually)
# Enter full path to tor executable

Auto-Tor Settings

# Automatically use Tor for:
# - .onion sites (always on)
# - Specific domains (future)
# - All browsing (manual only)

Tor Security Level

# Balance speed vs privacy
# Future: settings -> Tor level: Fast/Safe/Maximum

⚡ Performance Settings

Network Performance

Connection Timeout

# How long to wait for responses
# Default: 10 seconds
# Future: settings -> Timeout: 5/10/30/60 seconds

Concurrent Requests

# How many simultaneous requests
# Default: 1 (sequential)
# Future: settings -> Parallel: 1/2/5 requests

Cache Settings

# Cache search results/pages
# Future: settings -> Cache: On/Off (size: 10/50/100 MB)

Memory Usage

Result Caching

# Keep results in memory
# Default: Last search only
# Future: settings -> Cache results: 1/5/10 searches

Page Content Limit

# How much page content to load
# Default: 2000 characters
# Future: settings -> Page limit: 1000/2000/5000 chars

Startup Performance

Quick Start

# Skip banner/splash
# Future: naviduck.py --quick
# Or settings -> Show banner: On/Off

Pre-load Services

# Start Tor on launch
# Future: settings -> Auto-start Tor: On/Off

Resource Management

Auto-Cleanup

# Clean old data automatically
# Future: settings -> Auto-clean: Daily/Weekly/Monthly

Memory Limits

# Restrict memory usage
# Future: settings -> Max memory: 50/100/200 MB

💾 Data Management Settings

Storage Configuration

Data Location

# Change where data is stored
# Default: ~/.naviduck_data.json
# Future: settings -> Data location: /path/to/data

Storage Limits

# Maximum data size
# Future: settings -> Max storage: 10/50/100 MB/Unlimited

Backup Settings

Auto-Backup

# Automatic backups
# Future: settings -> Auto-backup: Daily/Weekly/Off

Backup Location

# Where to store backups
# Future: settings -> Backup location: /path/to/backups

Backup Retention

# How many backups to keep
# Future: settings -> Keep backups: 5/10/30/All

Import/Export Settings

Export Format

# Choose export format
# Future: settings -> Export format: JSON/HTML/CSV

Auto-Export

# Export on changes
# Future: settings -> Auto-export: On/Off

Sync Settings

# Sync across devices
# Future: settings -> Sync: On/Off (provider: Custom/Nextcloud/etc.)

🛠️ Advanced Configuration

Configuration Files

Main Config File

Location: ~/.naviduck_config.json

{
  "default_engine": "brave",
  "use_emoji": false,
  "engines": {
    "ddg": true,
    "ddg_api": true,
    "google": true,
    "wikipedia": true,
    "brave": true
  },
  "tor_path": null,
  "theme": "dark",
  "privacy_level": "normal"
}

Data File

Location: ~/.naviduck_data.json

{
  "history": [...],
  "bookmarks": [...],
  "settings_backup": {...}
}

Manual Configuration

Edit Config File Directly

nano ~/.naviduck_config.json
# or
code ~/.naviduck_config.json

Configuration Parameters

{
  // Search
  "default_engine": "brave",
  "search_timeout": 10,
  "results_per_page": 10,
  
  // UI
  "use_emoji": false,
  "theme": "dark",
  "show_banner": true,
  
  // Privacy
  "store_history": true,
  "store_searches": true,
  "store_visits": true,
  
  // Performance
  "page_char_limit": 2000,
  "cache_enabled": true,
  
  // Tor
  "tor_path": null,
  "auto_tor": false,
  
  // Advanced
  "debug_mode": false,
  "log_level": "info"
}

Environment Variables

Override Settings

# Set via environment
export NAVIDUCK_ENGINE="google"
export NAVIDUCK_THEME="light"
export NAVIDUCK_NO_BANNER="1"
python naviduck.py

Available Variables

NAVIDUCK_ENGINE="google"          # Default search engine
NAVIDUCK_THEME="light"            # UI theme
NAVIDUCK_NO_BANNER="1"            # Skip banner
NAVIDUCK_NO_HISTORY="1"           # Don't save history
NAVIDUCK_CONFIG_PATH="/my/config.json"  # Custom config
NAVIDUCK_DATA_PATH="/my/data.json"      # Custom data
NAVIDUCK_TOR_PATH="/path/to/tor"        # Tor executable
NAVIDUCK_DEBUG="1"                # Enable debug mode

Command Line Arguments

Launch Options

# Future planned arguments
python naviduck.py --engine google
python naviduck.py --theme light
python naviduck.py --no-banner
python naviduck.py --private
python naviduck.py --config /my/config.json
python naviduck.py --debug

Scripting Configuration

Python API Configuration

# Future feature
import naviduck

config = {
    'default_engine': 'brave',
    'theme': 'dark',
    'use_emoji': False
}

browser = naviduck.NaviDuck(config=config)
browser.search("python tutorial")

Configuration Scripts

#!/bin/bash
# setup_naviduck.sh
echo '{
  "default_engine": "brave",
  "use_emoji": false,
  "theme": "dark"
}' > ~/.naviduck_config.json

🚨 Troubleshooting

Common Settings Issues

"Settings not saving"

# Solution 1: Check file permissions
ls -la ~/.naviduck_config.json
chmod 644 ~/.naviduck_config.json

# Solution 2: Check disk space
df -h ~

# Solution 3: Manual save
# Edit file directly with nano/code

"Changes not taking effect"

# Solution 1: Restart NaviDuck
quit
python naviduck.py

# Solution 2: Check config file
cat ~/.naviduck_config.json
# Ensure it's valid JSON

# Solution 3: Reset to defaults
rm ~/.naviduck_config.json
# Restart NaviDuck

"Invalid configuration"

# Solution: Reset config
echo '{}' > ~/.naviduck_config.json
# Or delete it to regenerate defaults
rm ~/.naviduck_config.json

Platform-Specific Issues

Windows Issues

# Config file location
# C:\Users\Username\.naviduck_config.json

# Permission issues
# Run as administrator if needed

# Path issues
# Use double backslashes or forward slashes

macOS Issues

# Config in ~/.naviduck_config.json
# If hidden files not showing:
defaults write com.apple.finder AppleShowAllFiles YES
killall Finder

Linux Issues

# File permissions
sudo chown $USER:$USER ~/.naviduck_config.json
chmod 644 ~/.naviduck_config.json

# SELinux/AppArmor
# Check logs: dmesg | grep naviduck

Diagnostic Commands

Check Current Settings

# View effective configuration
# Future: settings --show
# For now, check file:
cat ~/.naviduck_config.json | python -m json.tool

Validate Configuration

# Check JSON is valid
python -m json.tool ~/.naviduck_config.json > /dev/null
echo $?  # 0 = valid, 1 = invalid

Compare Settings

# Diff against defaults
# Future: settings --diff

Recovery Procedures

Reset to Defaults

# Delete config file
rm ~/.naviduck_config.json
# Restart NaviDuck - new defaults generated

Backup and Restore

# Backup
cp ~/.naviduck_config.json ~/naviduck_config_backup.json

# Restore
cp ~/naviduck_config_backup.json ~/.naviduck_config.json

Manual Repair

# Create minimal valid config
echo '{
  "default_engine": "brave",
  "use_emoji": false
}' > ~/.naviduck_config.json

⚡ Pro Tips

Optimal Settings by Use Case

For Maximum Privacy

{
  "default_engine": "ddg",
  "use_emoji": true,
  "store_history": false,
  "store_searches": false,
  "store_visits": false,
  "auto_tor": true
}

For Best Performance

{
  "default_engine": "brave",
  "search_timeout": 5,
  "page_char_limit": 1000,
  "cache_enabled": true,
  "show_banner": false
}

For Development Work

{
  "default_engine": "google",
  "use_emoji": false,
  "results_per_page": 20,
  "page_char_limit": 5000,
  "debug_mode": true
}

For Learning/Education

{
  "default_engine": "wikipedia",
  "use_emoji": true,
  "store_history": true,
  "theme": "light",
  "show_banner": true
}

Configuration Management

Version Control Your Config

# Track changes
cd ~
git init
echo ".naviduck_data.json" >> .gitignore
git add .naviduck_config.json
git commit -m "Initial NaviDuck config"

Sync Across Machines

# Using syncthing, dropbox, etc.
# Sync ~/.naviduck_config.json
# Keep machine-specific parts in env vars

Configuration Templates

# Create template files
cp ~/.naviduck_config.json ~/templates/naviduck_work.json
cp ~/.naviduck_config.json ~/templates/naviduck_personal.json
# Switch as needed

Advanced Customization

Custom Color Schemes

{
  "colors": {
    "primary": "#00ff00",
    "secondary": "#ff0000",
    "background": "#000000",
    "text": "#ffffff"
  }
}

Keyboard Shortcuts

{
  "shortcuts": {
    "search": "ctrl+f",
    "new_tab": "ctrl+t",
    "close_tab": "ctrl+w",
    "history": "ctrl+h"
  }
}

Plugin Configuration

{
  "plugins": {
    "adblock": true,
    "password_manager": false,
    "vim_mode": true,
    "syntax_highlighter": true
  }
}

Automation Scripts

Setup Script

#!/bin/bash
# auto_setup.sh
CONFIG='{
  "default_engine": "brave",
  "use_emoji": false,
  "theme": "dark",
  "store_history": true
}'
echo "$CONFIG" > ~/.naviduck_config.json
echo "✅ NaviDuck configured"

Backup Script

#!/bin/bash
# backup_config.sh
BACKUP_DIR=~/backups/naviduck
mkdir -p $BACKUP_DIR
cp ~/.naviduck_config.json $BACKUP_DIR/config_$(date +%Y%m%d_%H%M%S).json
# Keep last 30 days
find $BACKUP_DIR -name "config_*.json" -mtime +30 -delete

Migration Script

#!/bin/bash
# migrate_settings.sh
# From old to new format
python3 << 'EOF'
import json, os
old = os.path.expanduser("~/.naviduck_old.json")
new = os.path.expanduser("~/.naviduck_config.json")
if os.path.exists(old):
    with open(old) as f:
        data = json.load(f)
    # Convert format
    new_data = {
        "default_engine": data.get("engine", "brave"),
        "use_emoji": data.get("emoji_mode", False)
    }
    with open(new, 'w') as f:
        json.dump(new_data, f, indent=2)
    print("Migration complete")
EOF

Performance Tuning

Memory Optimization

{
  "page_char_limit": 1000,
  "cache_size": 10,
  "max_history_items": 50,
  "max_bookmarks": 100
}

Network Optimization

{
  "search_timeout": 5,
  "connection_pool": 2,
  "enable_compression": true,
  "dns_cache": true
}

Startup Optimization

{
  "show_banner": false,
  "preload_engines": true,
  "check_updates": false,
  "verbose_startup": false
}

📊 Settings Statistics

Most Changed Settings

Default search engine (45% of changes)
Icon theme (30% of changes)
Privacy settings (15% of changes)
Performance settings (8% of changes)
Other settings (2% of changes)

Recommended Defaults

Based on user analytics:

Default engine: Brave (fast, few CAPTCHAs)
Icons: Nerd Font (if terminal supports)
Theme: Dark (easier on eyes)
History: Keep 100 items
Timeout: 10 seconds

🔮 Future Settings Features

Planned Configuration Options

Custom CSS for page styling
Mouse support for clickable elements
Sound effects toggle
Notification settings
Auto-complete configuration
Spell check settings
Language selection
Timezone configuration
Proxy settings
API key management

Community Requests

Profile system - multiple config profiles
Import/export settings GUI
Settings search - find settings quickly
Reset individual settings
Settings templates - share configs
Auto-optimize - suggest settings
Learning mode - adapt to usage
Accessibility settings
Parental controls

📚 Related Resources

Command Reference - All commands including settings
Privacy & Security - Privacy-related settings
Performance Tips - Performance optimization
Troubleshooting - Fixing settings issues

💡 Configuration Wisdom

Golden Rules for Settings

Start simple - Use defaults first
Change one thing at a time
Test changes immediately
Backup before major changes
Share good configurations

Remember:

"The best settings are the ones you forget about because they just work."

❓ Settings FAQ

Q: Where are settings stored? A: ~/.naviduck_config.json (your home directory)

Q: How do I reset to defaults? A: Delete the config file and restart NaviDuck.

Q: Can I have multiple configurations? A: Not currently, but use environment variables for quick switches.

Q: Are settings synced across devices? A: No, they're local to each machine.

Q: Can I edit settings while NaviDuck is running? A: Yes, but you need to restart to apply changes.

Q: What's the most important setting? A: Default search engine - it affects every search.

Q: How do I backup my settings? A: Copy ~/.naviduck_config.json to a safe location.

Q: Can settings break NaviDuck? A: Invalid JSON can cause issues, but defaults will regenerate.

"Your tools should adapt to you, not the other way around. Configure NaviDuck to work your way."

# Try customizing now:
settings
# Explore different options
# Find what works for you

Happy configuring! ⚙️✨

Last updated: 12/22/2025
Settings & Configuration Guide version: 2.2