Configuration

md2do uses hierarchical configuration with multiple sources that merge together.

Quick Start

Create .md2do.json in your project root:

{
  "defaultAssignee": "yourname",
  "todoist": {
    "apiToken": "your-api-token",
    "defaultProject": "Inbox"
  }
}

That's it! md2do will find and use this config automatically.

Configuration Precedence

Configs merge in this order (later overrides earlier):

1. Default values (built into md2do)
2. Global config (~/.md2do.json)
3. Project config (./.md2do.json)
4. Environment variables (TODOIST_API_TOKEN)

Example flow:

# Global config sets your default name
~/.md2do.json: { "defaultAssignee": "alice" }

# Project config sets Todoist project
./project/.md2do.json: { "todoist": { "defaultProject": "Work" } }

# Environment overrides API token
export TODOIST_API_TOKEN="secret-token"

# Final merged config:
{
  "defaultAssignee": "alice",    # from global
  "todoist": {
    "apiToken": "secret-token",  # from environment
    "defaultProject": "Work"     # from project
  }
}

Config File Locations

Global Config

Place in your home directory:

• ~/.md2do.json
• ~/.md2do.yaml
• ~/.md2do.js

Use for: Settings you want across all projects (your username, output preferences).

Project Config

Place in project root:

• ./.md2do.json
• ./.md2do.yaml
• ./.md2do.js
• ./md2do.config.js

Use for: Project-specific settings (Todoist project, markdown paths, team tags).

Supported Formats

JSON

.md2do.json:

{
  "defaultAssignee": "alice",
  "output": {
    "format": "pretty",
    "colors": true
  }
}

YAML

.md2do.yaml:

defaultAssignee: alice
output:
  format: pretty
  colors: true

JavaScript

.md2do.js:

module.exports = {
  defaultAssignee: 'alice',
  output: {
    format: 'pretty',
    colors: true,
  },
};

Configuration Options

Markdown Settings

Control file scanning:

{
  "markdown": {
    "root": "./docs",
    "pattern": "**/*.md",
    "exclude": ["node_modules/**", "drafts/**", ".git/**"]
  }
}

Options:

• root - Directory to start scanning (default: .)
• pattern - Glob pattern for markdown files (default: **/*.md)
• exclude - Patterns to skip (default: ["node_modules/**", ".git/**"])

Todoist Settings

Configure Todoist integration:

{
  "todoist": {
    "apiToken": "your-token",
    "defaultProject": "Inbox",
    "autoSync": false,
    "syncDirection": "both"
  }
}

Options:

• apiToken - Your Todoist API token
• defaultProject - Default project name for new tasks
• autoSync - Auto-sync after task changes (default: false)
• syncDirection - Sync mode: "push", "pull", or "both" (default: "both")

See Todoist Integration for setup details.

Output Settings

Customize output formatting:

{
  "output": {
    "format": "pretty",
    "colors": true,
    "paths": true
  }
}

Options:

• format - Output style: "pretty", "table", or "json" (default: "pretty")
• colors - Enable colored output (default: true)
• paths - Show file paths (default: true)

Default Assignee

Set your username:

{
  "defaultAssignee": "yourname"
}

Useful for filtering "my tasks" quickly.

Environment Variables

Override config with environment variables:

# Todoist API token (most common)
export TODOIST_API_TOKEN="your-token"

# Default assignee
export MD2DO_DEFAULT_ASSIGNEE="alice"

Environment variables always win - they override all config files.

Common Configurations

Personal Setup

~/.md2do.json:

{
  "defaultAssignee": "yourname",
  "output": {
    "format": "pretty",
    "colors": true
  },
  "todoist": {
    "apiToken": "your-personal-token"
  }
}

Team Project

.md2do.json (committed to git):

{
  "markdown": {
    "root": "./docs",
    "exclude": ["drafts/**", "archive/**"]
  },
  "todoist": {
    "defaultProject": "Team Project"
  }
}

Important: Don't commit apiToken! Use environment variables or global config for secrets.

Work vs Personal

Global config (~/.md2do.json):

{
  "defaultAssignee": "alice",
  "output": {
    "colors": true
  }
}

Work project (~/work/project/.md2do.json):

{
  "todoist": {
    "apiToken": "work-token",
    "defaultProject": "Client Work"
  }
}

Personal project (~/personal/.md2do.json):

{
  "todoist": {
    "apiToken": "personal-token",
    "defaultProject": "Personal"
  }
}

Documentation Project

For projects with markdown docs:

{
  "markdown": {
    "root": "./documentation",
    "pattern": "**/*.md",
    "exclude": ["node_modules/**", "build/**", "api-reference/**"]
  },
  "defaultAssignee": "docs-team"
}

Security Best Practices

Never Commit Secrets

Add to .gitignore:

# md2do config with secrets
.md2do.json
.md2do.local.json

Use Environment Variables

For CI/CD or shared machines:

# .env file (also add to .gitignore)
TODOIST_API_TOKEN=your-secret-token

# Use in scripts
export $(cat .env | xargs)
md2do list

Restrict File Permissions

Protect your config:

chmod 600 ~/.md2do.json

Share Structure, Not Secrets

Commit this:

{
  "markdown": {
    "root": "./docs"
  },
  "todoist": {
    "defaultProject": "Team Project"
    // apiToken loaded from environment
  }
}

Not this:

{
  "todoist": {
    "apiToken": "abc123secret" // ❌ Never commit!
  }
}

Validation

md2do validates your config automatically. Invalid configs show helpful errors:

$ md2do list
Error: Invalid configuration:
- todoist.syncDirection must be 'push', 'pull', or 'both'

Debugging Config

See what config md2do is using:

# Show effective configuration
md2do config show

# Show config sources
md2do config sources

# Validate current config
md2do config validate

(Commands coming soon)

Complete Example

Full configuration with all options:

{
  "markdown": {
    "root": "./documentation",
    "pattern": "**/*.md",
    "exclude": ["node_modules/**", "drafts/**", ".git/**", "dist/**"]
  },
  "defaultAssignee": "alice",
  "todoist": {
    "apiToken": "your-token-here",
    "defaultProject": "Work",
    "autoSync": false,
    "syncDirection": "both"
  },
  "output": {
    "format": "pretty",
    "colors": true,
    "paths": true
  }
}

Next Steps

• Todoist Integration - Configure Todoist sync
• Task Format - Learn task syntax
• Filtering - Query your tasks
• Examples - Real-world setups