Skip to content

configuration.md

Latest commit

 

History

History
495 lines (393 loc) · 8.96 KB

configuration.md

File metadata and controls

495 lines (393 loc) · 8.96 KB

Configuration Guide

NoteDown supports both global and repository-specific configuration. This guide covers all available options and how to customize your setup.

📋 Table of Contents

Configuration Files

NoteDown uses two types of configuration files:

Global Config

  • Location: ~/.config/noted/config.yaml
  • Purpose: System-wide settings, default repository
  • Scope: All noted repositories

Local Config

  • Location: .noted (in repository root)
  • Purpose: Repository-specific settings and index
  • Scope: Current repository only

Global Configuration

The global config is automatically created at ~/.config/noted/config.yaml.

Default Global Config

version: "1.0"
defaults:
  default_editor: "nano"
  ignore_files:
    - ".git/"
    - "*.tmp"
    - "*.swp"
    - ".DS_Store"
paths: {}
default_repository: ""
llm:
  provider: ""
  api_key: ""
  model: ""

Configuration Options

Editor Settings

defaults:
  default_editor: "code"        # Default: "nano"
  # Options: "code", "vim", "nano", "emacs", custom command

Default Repository

default_repository: "/home/user/notes"
# Used for quick snippets: noted "text"

Ignore Patterns

defaults:
  ignore_files:
    - ".git/"
    - "node_modules/"
    - "*.log"
    - "*.tmp"
    - ".DS_Store"

LLM Integration (Future Feature)

llm:
  provider: "openai"        # "openai", "gemini", etc.
  api_key: "your-api-key"   # Store securely
  model: "gpt-3.5-turbo"    # Model name

Managing Global Config

View Current Config

# Display current global configuration
noted config show

# Show specific setting
noted config get default_editor

Update Settings

# Set default editor
noted config set default_editor code

# Set default repository
noted set default ~/my-notes

# Add ignore pattern
noted config add ignore_pattern "*.backup"

Local Configuration

Each repository has a .noted file containing repository-specific settings and indexes.

Default Local Config

version: "1.0"
defaults:
  default_editor: ""
  ignore_files: []
paths: {}
index: []
assets: []

Repository-Specific Settings

Override Global Defaults

defaults:
  default_editor: "vim"       # Override global setting for this repo
  ignore_files:
    - "drafts/"              # Additional ignore patterns
    - "private/"

Custom Paths

paths:
  templates: "./templates"     # Custom template directory
  exports: "./exports"         # PDF export directory
  assets: "./assets"          # Asset directory (default)

Index Configuration

The index section is managed automatically but can be customized:

index:
  - path: "note.md"
    title: "My Note"
    tags: ["example", "documentation"]
    created_at: "2025-08-28T14:30:00Z"
    updated_at: "2025-08-28T15:45:00Z"
    word_count: 342

Asset Index

Assets are automatically indexed:

assets:
  - path: "assets/images/diagram.png"
    name: "diagram.png"
    type: "image"
    size: 245760
    mime_type: "image/png"
    created_at: "2025-08-28T10:15:00Z"
    description: "System architecture diagram"

Environment Variables

NoteDown respects several environment variables:

Editor Selection

export NOTED_EDITOR="code"      # NoteDown-specific editor
export EDITOR="vim"             # Fallback to system editor
export VISUAL="code"            # Visual editor fallback

Git Configuration

export GIT_AUTHOR_NAME="Your Name"
export GIT_AUTHOR_EMAIL="you@example.com"

Custom Paths

export NOTED_CONFIG_DIR="~/.config/noted"
export NOTED_TEMPLATES_DIR="~/.noted-templates"

Templates

Templates help create consistent note structures.

Default Template Location

  • Global: ~/.config/noted/templates/
  • Local: <repo>/templates/

Basic Template

# ~/.config/noted/templates/basic.md
---
title: "{{title}}"
tags: []
category: "notes"
created_at: {{timestamp}}
---

# {{title}}

## Overview


## Details


## References

Research Template

# ~/.config/noted/templates/research.md
---
title: "{{title}}"
tags: ["research", "draft"]
category: "study"
source: ""
author: ""
date_published: ""
---

# {{title}}

## Summary


## Key Findings
- 

## Methodology


## References
- Source: {{source}}

## Notes and Thoughts

Meeting Template

# ~/.config/noted/templates/meeting.md
---
title: "{{title}}"
tags: ["meeting"]
category: "work"
attendees: []
date: {{date}}
---

# {{title}}

**Date**: {{date}}  
**Attendees**: 

## Agenda


## Discussion


## Action Items
- [ ] 

## Next Steps

Using Templates

# Create note from template
noted new "Research Paper Analysis" --template=research

# List available templates
noted templates list

# Create custom template
noted templates create meeting-notes

Ignore Patterns

Control which files are indexed and tracked.

Global Ignore Patterns

Set in global config:

defaults:
  ignore_files:
    - ".git/"
    - "node_modules/"
    - "*.log"
    - "*.tmp"
    - ".DS_Store"
    - "Thumbs.db"

Local Ignore File

Create .notedignore in repository root:

# Ignore drafts and private notes
drafts/
private/
*.draft.md

# Ignore temporary files
*.tmp
*.bak
*~

# Ignore large media files
*.mp4
*.avi
*.mkv

# Ignore specific directories
node_modules/
.git/

Ignore Syntax

# Directory (recursive)
directory/

# File extension
*.extension

# Specific file
filename.md

# Pattern matching
temp_*
*_backup

# Comments
# This is a comment

VSCode Settings

Configure the VSCode extension through settings.json:

Basic Extension Settings

{
    "notedown.executablePath": "noted",
    "notedown.autoSave": true,
    "notedown.autoSaveDelay": 2000,
    "notedown.defaultTemplate": "basic"
}

Editor Customization

{
    "notedown.editor.enableLivePreview": true,
    "notedown.editor.enableSlashCommands": true,
    "notedown.editor.wordWrap": "bounded",
    "notedown.editor.fontSize": 14,
    "notedown.editor.lineHeight": 1.5,
    "notedown.editor.fontFamily": "JetBrains Mono, Consolas, monospace"
}

Theme and UI

{
    "notedown.theme.accentColor": "#007ACC",
    "notedown.theme.darkMode": "auto",
    "notedown.ui.showWordCount": true,
    "notedown.ui.showTags": true,
    "notedown.ui.compactMode": false
}

Performance Settings

{
    "notedown.indexing.watchFiles": true,
    "notedown.indexing.maxFiles": 5000,
    "notedown.indexing.maxFileSize": "10MB",
    "notedown.indexing.skipLargeFiles": true,
    "notedown.indexing.skipBinaryFiles": true
}

Git Integration

{
    "notedown.git.autoCommit": true,
    "notedown.git.commitMessage": "Auto-save: {{timestamp}}",
    "notedown.git.autoSync": false,
    "notedown.git.syncOnSave": false
}

Configuration Examples

Personal Knowledge Base Setup

# Global config for personal use
version: "1.0"
default_repository: "/home/user/personal-notes"
defaults:
  default_editor: "code"
  ignore_files:
    - ".git/"
    - "*.tmp"
    - "drafts/"
    - "private/"

# Local repo config
defaults:
  ignore_files:
    - "journal/private/"
paths:
  templates: "./templates"
  exports: "./exports"

Team Documentation Setup

# Shared repository config
version: "1.0"
defaults:
  default_editor: "code"
  ignore_files:
    - ".git/"
    - "node_modules/"
    - "*.log"
    - "drafts/"
paths:
  templates: "./team-templates"
  exports: "./shared-exports"

Research Repository Setup

# Academic/research focused
version: "1.0"
defaults:
  ignore_files:
    - ".git/"
    - "raw-data/"
    - "*.pdf"  # Don't index PDFs, just reference them
    - "temp/"
paths:
  assets: "./research-assets"
  exports: "./papers"

Best Practices

1. Configuration Management

  • Keep global config minimal
  • Use local config for repository-specific needs
  • Version control your local .noted file
  • Don't version control sensitive data (API keys)

2. Template Organization

  • Create templates for common note types
  • Use consistent frontmatter across templates
  • Include placeholder text for guidance
  • Share templates across team repositories

3. Ignore Patterns

  • Be specific with ignore patterns
  • Include common temporary files
  • Ignore large binary files
  • Document special ignore needs

4. Editor Integration

  • Configure your preferred editor globally
  • Use VSCode extension for rich editing
  • Set up keyboard shortcuts
  • Customize theme and appearance

Next: Learn about advanced workflows and optimization techniques.

← Previous: VSCode Extension | Next: Best Practices → | Back to README